Overview

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. To simplify usage, Beacon allows you to create/insert, update and delete data directly from an HTML form using a simple submit action.


There are two kinds of POST requests in Beacon: Simple and Complex. Simple POST requests are those that insert, update or delete a record against a single entity, like the contact entity. Complex POST 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.


Copy and paste the following URL into your browser; substitute the token provided to your organization in place of the text "yourtokenhere" and hit ENTER. If you don't have a token, please contact support.

 

Create/Insert Records


https://data.peak15systems.com/beacon/service.svc/insert/entity/contact
?token=yourtokenhere
&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


The following simple HTML form will also create a contact after substituting in your token


   

 <html>
    <head>
        <title>Beacon Sample: Insert Contact</title>
    </head>
    <body>
        <form action="https://data.peak15systems.com/beacon/service.svc/insert/entity/contact"
              method="post" enctype="application/x-www-form-urlencoded">
            <input type="hidden" name="token" value="yourtokenhere" />
            First Name
            <input type="text" name="firstname" maxlength="50" value="Hello" />
            Last Name
            <input type="text" name="lastname" maxlength="50" value="World" />
            <input type="hidden" name="p15_contacttype_contactid" value="Prospect" />
            <input type="submit" value="Submit" />
        </form>
    </body>
</html>


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:


https://data.peak15systems.com/beacon/service.svc/insert/entity/[entityname]
   ?token=yourtokenhere
   &[attribute1 name]=[attribute1 value]
   &[attribute2 name]=[attribute2 value]
   ...
   &[attributeN name]=[attribute2 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:


https://data.peak15systems.com/beacon/service.svc/insert/entity/annotation?
token=[yourtokenhere]
&subject=[subject]
&notetext=[notetext]
&objecttypecode=[entityname]
&objectid=[recordGUID]


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:


https://data.peak15systems.com/beacon/service.svc/insert/entity/annotation?
token=[yourtokenhere]
&subject=[subject]
&notetext=[notetext]
&objecttypecode=[entityname]
&objectid=[recordGUID]
&filename=[filename (e.g., passport.pdf)]
&mimetype=[file type (e.g., application/pdf, text/plain)]
&isencoded=[true or false]
&documentbody=[the file itself]


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.


Non AJAX sample

AJAX sample


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:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/[entityname]?token=[yourtokenhere]


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:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&columns=[column1,column2,column3,etc...]


For example, you could limit the contact entity attributes returned to just firstname and lastname like this:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
contact?token=[yourtokenhere]&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:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&[parameter1][operator1][value1]&[parameter2][operator2][value2]


For example, you could filter your results by the status and createdby attributes, which all entities include, like this:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?statecodename=Active&createdbyname=John%20Doe


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:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&statecode=0&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, 2009, you would use:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?createdon=2009-01-01


And to get all records created on or after Jan 1st, 2009, you would use:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&createdon=>2008-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:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&pagingcookie=2


In addition, you can change the number of records that are returned from the default of 50 to another value by calling:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&count=100


You can also change the sort order of records that are returned by calling:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?orderby=[attributename]


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:


https://data.peak15systems.com/beacon/service.svc/get/[orgname]/entity/
[entityname]?token=[yourtokenhere]&count=100&amp;pagingcookie=2&amp;orderby=modifiedon


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:


https://data.peak15systems.com/beacon/service.svc/update/entity/contact
   ?token=yourtokenhere
   &contactid=[contactGUID]
   &emailaddress1=[updated email]


In this example, we update the status reason of an existing contact:


https://data.peak15systems.com/beacon/service.svc/update/entity/contact
   ?token=yourtokenhere
   &contactid=[contactGUID]
   &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:


https://data.peak15systems.com/beacon/service.svc/update/entity/contact
   ?token=yourtokenhere
   &contactid=[contactGUID]
   &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:


https://data.peak15systems.com/beacon/service.svc/assign/entity/contact
   ?token=yourtokenhere
   &entityd=[contactGUID]
   &userid=[userGUID 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:


https://data.peak15systems.com/beacon/service.svc/delete/entity/contact
   ?token=yourtokenhere
   &contactid=[contactGUID]