Overview
NOTE: We strongly recommend using HTTP POST method for all calls. This allows you to send parameters including the token in the payload of the message which increases security.
Beacon has functions allow you to create/insert, read, update and delete one or more records by posting name/value pairs, to which you will receive a success or error message. Note that all requests happen over https using SSL.
There are two kinds of requests in Beacon: Simple and Complex. Simple requests are those that insert, update or delete a record against a single entity, like the contact entity. Complex requests take form data and insert, update or delete linked records against multiple entities, like the contact and inquiry entity.
NOTE: The Beacon web services accept a max URL length of 16,000 characters. When testing by inserting URLs into a browser, however, your browser may have its own URL length limit.
Create/Insert Records
POST /beacon/service.svc/insert/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &firstname=Hello &lastname=World &p15_contacttype_contactid=Prospect
The response you get back will the Globally Unique ID (aka GUID) for the new contact and will look like this:
E8064816-EB23-DE11-8408-005056B97005
In order to do an insert on other entities, you must first determine the name of the entity; the names of its required attributes and the names of any other standard PEAK 15 or custom attributes you will be including. Once you have those names, simply use the following syntax:
POST /beacon/service.svc/insert/entity/your-entity-name HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &your-attribute1-name=your-attribute1-value &your-attribute2-name=your-attribute2-value &your-attributeN-name=your-attributeN-value
All records in PEAK 15 can have notes or annotations appended to them using a simple insert like this if you have the GUID of the record you are appending the note to:
POST /beacon/service.svc/insert/entity/annotation HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &subject=your-subject-here ¬etext=your-notetext-here &objecttypecode=related-entityname-here &objectid=related-recordGUID-here
In the example above, if you are appending a note to a contact the objecttypecode would be “contact” or “p15_bookings” if you were appending to a booking.
You can also upload a file as part of a note. However, if using a HTTP GET you will be constrained by the URL length limit of the Beacon web service which is 16,000 characters. For that reason it is recommended you use HTTP POST and put the file contents in the body of the message. Even then the system currently has a 5 MB file size limitation. The syntax is:
POST /beacon/service.svc/insert/entity/annotation HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &subject=your-subject-here ¬etext=your-notetext-here &objecttypecode=related-entityname-here &objectid=related-recordGUID-here &filename=your-filename-here &mimetype=your-filetype-here &isencoded=true or false &documentbody=your-file-here
We have created two sample html pages that show how your forms might process a file selected by the form user and validate its size doesn't exceed the limit. Note that these samples are provided "as is" and are not part of the system.
Read/Get Records
Beacon’s GET methods allow you to submit a request as a simple URL and get back a list of records. When submitting a request, you must now include your token. The following will return all records from a single entity:
NOTE: We strongly recommend using HTTP POST method for all calls. This allows you to send parameters including the token in the payload of the message which increases security.
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here
The response message will be XML like this:
<resultset morerecords="0" paging-cookie="">
<cookie page="1">
<contactid last="{E8064816-EB23-DE11-8408-005056B97005}" first="{BE13E490-0B23-DE11-8408-005056B97005}">
</contactid></cookie>">
<result>
<contactid>BE13E490-0B23-DE11-8408-005056B97005</contactid>
<firstname>Hello</firstname>
<lastname>World</lastname>
<p15_contacttype_contactid>Prospect</p15_contacttype_contactid>
<statuscode name="Active">1</statuscode>
<statecode name="Active">0</statecode>
<createdby dsc="0" name="John Doe">{BBB275C7-1F05-DE11-8D91-005056B97005}</createdby>
<createdon date="4/6/2009" time="5:32 PM">2009-04-06T17:32:26-07:00</createdon>
<modifiedby dsc="0" name="John Doe">{ BBB275C7-1F05-DE11-8D91-005056B97005}</modifiedby>
<modifiedon date="4/6/2009" time="5:32 PM">2009-04-06T17:32:26-07:00</modifiedon>
<ownerid type="8" name="John Doe" dsc="0">{BBB275C7-1F05-DE11-8D91-005056B97005}</ownerid>
<owningbusinessunit>{AE316470-5704-DE11-8D91-005056B97005}</owningbusinessunit>
</result>
<result>
<contactid>BE13E490-0B23-DE11-8408-005056B97005</contactid>
<firstname>Hello</firstname>
<lastname>World2</lastname>
<p15_contacttype_contactid>Prospect</p15_contacttype_contactid>
<statuscode name="Active">1</statuscode>
<statecode name="Active">0</statecode>
<createdby dsc="0" name="John Doe">{BBB275C7-1F05-DE11-8D91-005056B97005}</createdby>
<createdon date="4/6/2009" time="5:32 PM">2009-04-06T17:32:26-07:00</createdon>
<modifiedby dsc="0" name="John Doe">{ BBB275C7-1F05-DE11-8D91-005056B97005}</modifiedby>
<modifiedon date="4/6/2009" time="5:32 PM">2009-04-06T17:32:26-07:00</modifiedon>
<ownerid type="8" name="John Doe" dsc="0">{BBB275C7-1F05-DE11-8D91-005056B97005}</ownerid>
<owningbusinessunit>{AE316470-5704-DE11-8D91-005056B97005}</owningbusinessunit>
</result>
</resultset>By default, Beacon will return the first 50 active records and all attributes that contain data. You can control which attributes you want returned and the order in which the attributes are returned, although the ID of the record is always returned as the last column if it isn't specifically requested elsewhere in the column order. The general format is:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &columns=your-attributename-1,your-attributename-2,your-attribute-nameN
For example, you could limit the contact entity attributes returned to just firstname and lastname like this:
POST /beacon/service.svc/get/your-orgname-here/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &columns=firstname,lastname
NOTE: Attributes with NULL values will not be returned even if you specify them in the request.
You can also filter your result set using any combination of attributes in your result set as parameters with the equals (=) operator. The general format is:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &your-parameter-1 operator1 your-value-1 &your-parameter-2 operator2 your-value-2 &your-parameter-N operatorN your-value-N
For example, you could filter your results by the status and createdby attributes, which all entities include, like this:
POST /beacon/service.svc/get/your-orgname-here/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &statecodename%3DActive &createdbyname%3DJohn%2520Doe
Note how the example above-used statecodename with the value “Active” and createdbyname with the value “John Doe”. Picklist attributes and lookup attributes like these will show in the XML result set like:
<statecode name="Active">0</statecode>
<createdby name="John Doe" dsc="0">{BBB275C7-1F05-DE11-8D91-005056B97005}</createdby>This call would get the same results as the one using the name values:
POST /beacon/service.svc/get/your-orgname-here/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &statecodename=Active &createdby=BBB275C7-1F05-DE11-8D91-005056B97005
Every entity has at least two Date/Time attributes that you can use to narrow your result set: createdon and modifiedon. Some entities may have additional Date/Time attributes. For example, the Departures entity includes a Date/Time attribute for both Start Date and End Date. All Date/Time attributes support three types of operators: equals (=), less than (=<) and greater than (=>). Note that Beacon doesn’t currently support a “greater than or equal to” or “less than or equal to” operator but you can achieve the same result by incrementing your date by one second:
For example, to get all records created on Jan 1st, 2024, you would use:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &createdon=2024-01-01
And to get all records created on or after Jan 1st, 2024, you would use:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &createdon=>2023-12-31T23:59:59
Note that if you don’t include a time in a request that uses the greater than or less than as an operator, Beacon will interpret it as “T00:00:00”. Similarly, if you pass “T00:00”, Beacon will interpret that as “T00:00:00”). However, submitting “T00” will result in an error.
If there are more records than what was returned, the resultset element in the XML response message will have a morerecords attribute value of 1 or true like this:
<resultset morerecords="1" ...=""> </resultset>
You can get the next page of records by calling:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &pagingcookie=2
In addition, you can change the number of records that are returned from the default of 50 to another value by calling:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &count=100
You can also change the sort order of records that are returned by calling:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &orderby=your-attribute-name-here
NOTE: You can only order by one column and it will always return results in ascending order.
Finally, you can also combine these parameters using the “&” separator:
POST /beacon/service.svc/get/your-orgname-here/entity/your-entityname-here HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &pagingcookie=2 &count=100 &orderby=your-attribute-name-here
Update Records
Updates function just like inserts except that we must pass in the GUID of the record we are updating. In this example, we update the email address of an existing contact:
POST /beacon/service.svc/update/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &contactid=your-contact-GUID-here &emailaddress1=your-updated-email-here
In this example, we update the status reason of an existing contact:
POST /beacon/service.svc/update/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &contactid=your-contact-GUID-here &statuscode=Inactive
Note that passing a blank value for an attribute causes that attribute to be ignored. If you wish to set the value of an attribute to NULL, you must use the ASCII value of '%00'. For example, the following would result in the middle name being left with its current value but the comment being blanked out or set to NULL:
POST /beacon/service.svc/update/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &contactid=your-contact-GUID-here &middlename= &p15_comment=%00
Note that you can't directly update the owner of a record, to do that you need to use the assign function. In this example, we update the owner of an existing contact:
POST /beacon/service.svc/assign/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &contactid=your-contact-GUID-here &userid=your-user-GUID-or-name
Delete Records
Deletes function just like updates in that we must pass in the GUID of the record we are deleting. In this example, we delete an existing contact:
POST /beacon/service.svc/delete/entity/contact HTTP/1.1 Host: data.peak15systems.com Content-Type: application/x-www-form-urlencoded token=your-token-here &contactid=your-contact-GUID-here