Custom Object |
Accompa API version "2" and later:
This is supported in Accompa API version "2" and later.
Learn more about API versions |
| |
| This page explains how to use the Accompa REST API to manage records of a Custom Object: |
|
Read a Record
|
| Reading a record of a Custom Object is achieved via a HTTP GET request to its URI. |
| |
| GET /{api_prefix}/{id} |
| Returns a single record whose integer ID is {id}. {api_prefix} is the value of the <api_prefix> element in the API response to GET /object API request. |
| |
| RESPONSE |
Status: 200
<custom_object>
<fields>
<field>
<name>id</name>
<label>ID</label>
<value>55</value>
<prefix>CO-</prefix>
<sort>0</sort>
</field>
<field>
<name>field_49</name>
<label>Title</label>
<value>Save document as CSV file</value>
<sort>1</sort>
</field>
<field>
<name>field_50</name>
<label>Description</label>
<value><![CDATA[<b>Important:</b> We have received requests from many customers to allow them to save the file as a <i>CSV file</i> (see example of such a file at <a href="http://www.MyExampleDomain.com/example_file.csv">this link</a>) so that they can import into other software.]]></value>
<value_plaintext>Important: We have received requests from many customers to allow them to save the file as a CSV file (see example of such a file at this link) so that they can import into other software.</value_plaintext>
<sort>2</sort>
</field>
<field>
<name>field_51</name>
<label>Products</label>
<value id="5">Remarkable Spreadsheet</value>
<list_type>normal</list_type>
<sort>3</sort>
</field>
<field>
<name>field_52</name>
<label>Priority</label>
<value id="1">P1 - Highest</value>
<list_type>normal</list_type>
<sort>4</sort>
</field>
<field>
<name>field_57</name>
<label>Assigned To</label>
<value id="173" email="mickey.mouse@disney.com">Mickey Mouse</value>
<list_type>user</list_type>
<sort>5</sort>
</field>
...
...
...
<field>
<name>version_number</name>
<label>Version Number (Auto-generated)</label>
<value>2</value>
<sort />
</field>
<field>
<name>created_time</name>
<label>Created Time (GMT Timestamp)</label>
<value>1262920833</value>
<sort />
</field>
<field>
<name>last_updated_time</name>
<label>Last Updated Time (GMT Timestamp)</label>
<value>1273784841</value>
<sort />
</field>
</fields>
</custom_object> |
If a Record with ID matching {id} exists, an XML response will be generated along with the status code "200". The XML response will contain the data stored for that particular Record - and will include standard fields as well as custom fields. Contents of any "rich text" (Textarea) field will be returned as a CDATA section - i.e. starting with <![CDATA[ and ending with ]]> - containing HTML content.
If a Record with ID matching {id} does not exist, the response HTTP 404 "not found" will be returned. Other errors will return a response other than "200", usually along with an error message in XML format. |
| |
Create a Record
|
| Creating a record of a Custom Object is achieved via a HTTP POST request to the following URI. |
| |
| POST /{api_prefix} |
| Creates a single record. {api_prefix} is the value of the <api_prefix> element in the API response to GET /object API request. |
| |
| REQUEST |
<custom_object>
<fields>
<field>
<name>field_3005</name>
<value>Save document as CSV file</value>
</field>
<field>
<name>field_3006</name>
<value>We have received requests from many customers to allow them to save the file as a CSV file so that they can import into other software.</value>
</field>
<field>
<name>field_3007</name>
<value>2</value>
</field>
<field>
<name>field_3009</name>
<value>1</value>
</field>
<field>
<name>field_3010</name>
<value>5930</value>
</field>
...
</fields>
</custom_object> |
| |
| RESPONSE |
Status: 201
Location: https://www.accompa.com/api2/{api_key}/{api_prefix}/{id} |
, where {id} is the Record ID of the newly created record.
If a record is not created, a response other than "201" will be sent, usually along with an error message in XML format. |
| |
| In order to construct the request, you'll need a list of all available fields for the Record resource. You can retrieve this list via: |
| |
| GET /{api_prefix}/field |
| Returns a list of all fields available for this Custom Object resource. {api_prefix} is the value of the <api_prefix> element in the API response to GET /object API request. |
| |
| RESPONSE |
Status: 200
<custom_object_fields>
<fields>
<field>
<name>id</name>
<label>ID</label>
<type>Number-Integer</type>
<sort>0</sort>
<help>This is the unique ID for this record</help>
<required>0</{api_prefix}quired>
<default_value />
<max_size>15</max_size>
<special_purpose>id</special_purpose>
</field>
<field>
<id>3005</id>
<name>field_3005</name>
<label>Title</label>
<type>Textbox</type>
<sort>1</sort>
<help>Enter a brief title for this record.</help>
<required>1</{api_prefix}quired>
<default_value>0</default_value>
<max_size>255</max_size>
<special_purpose>title</special_purpose>
</field>
<field>
<id>3006</id>
<name>field_3006</name>
<label>Description</label>
<type>Textarea</type>
<sort>2</sort>
<help>Enter description for this record.</help>
<required>1</{api_prefix}quired>
<default_value>10</default_value>
<max_size>30000</max_size>
<special_purpose>desc</special_purpose>
</field>
<field>
<id>3007</id>
<name>field_3007</name>
<label>Products</label>
<type>Picklist-Pick Multiple</type>
<sort>3</sort>
<help>Select products that this record applies to.</help>
<required>1</{api_prefix}quired>
<default_value />
<max_size />
<special_purpose>product</special_purpose>
<picklist_options>
<option>
<value>1</value>
<label>Remarkable Writer</label>
<desc>This product is our online word processor.</desc>
<option_sort />
<option_default />
</option>
<option>
<value>2</value>
<label>Remarkable Spreadsheet</label>
<desc>This product is a spreadsheet product.</desc>
<option_sort />
<option_default />
</option>
<option>
<value>3</value>
<label>Remarkable Calc</label>
<desc />
<option_sort />
<option_default />
</option>
<option>
...
</option>
</picklist_options>
</field>
<field>
<id>3008</id>
<name>field_3008</name>
<label>Tags</label>
<type>Textbox</type>
<sort>4</sort>
<help>Tags are keywords or descriptive terms used to classify records. Tags are used to show similar records, and in searches.</help>
<required>0</{api_prefix}quired>
<default_value>0</default_value>
<max_size>255</max_size>
<special_purpose>tags</special_purpose>
</field>
<field>
<id>3009</id>
<name>field_3009</name>
<label>Status</label>
<type>Picklist-Pick One</type>
<sort>5</sort>
<help>Enter status of this record.</help>
<required>0</{api_prefix}quired>
<default_value />
<max_size />
<special_purpose>status</special_purpose>
<picklist_options>
<option>
<value>1</value>
<label>Pending Review</label>
<desc />
<option_sort />
<option_default />
</option>
<option>
<value>2</value>
<label>Accepted - Scheduled</label>
<desc />
<option_sort />
<option_default />
</option>
...
<option>
</option>
</picklist_options>
</field>
<field>
<id>3010</id>
<name>field_3010</name>
<label>Owner</label>
<type>Picklist-Pick One</type>
<sort>6</sort>
<help>Select the owner for this record. This person is currently responsible for this record.</help>
<required>0</{api_prefix}quired>
<default_value>0</default_value>
<max_size />
<special_purpose>owner</special_purpose>
<picklist_options>
<option>
<value>1</value>
<label>{{USERS}}</label>
<desc />
<option_sort />
<option_default />
</option>
</picklist_options>
</field>
...
</fields>
</custom_object_fields> |
When creating a record, don't include the field with <name> value of "id" - ID of a new record will be automatically assigned by the system. Please make sure to include all fields with <required> value of "1" in your request.
As you can see in the example above, picklist fields (such as 'Products' and 'Status' fields) will contain a <picklist_options> element which will list all available values for that field. For these picklist fields, set the <value> element in your request to appropriate integer value from one of the <value> elements in the response above. For picklist fields that accept multiple values (as indicated by <type>Picklist-Pick Multiple</type>) - set the <value> element in your request to a comma-separated string containing multiple integer values (example: <value>1,2,3</value>).
For picklist fields that contain a list of users on your system (such as 'Owner' field in the example above) - the response will contain only one child element within <picklist_options>, with <label> set to "{{USERS}}" . In these cases, you can get a list of all users on your system via: |
| |
| GET /user |
| Returns a list of all users on your system. |
| |
| RESPONSE |
Status: 200
<users>
<user>
<user_id>5840</user_id>
<email>mickey.mouse@disney.com</email>
<firstname>Mickey</firstname>
<lastname>Mouse</lastname>
<deleted />
<status>Active</status>
</user>
<user>
<user_id>5930</user_id>
<email>jason.bourne@treadstone.com</email>
<firstname>Jason</firstname>
<lastname>Bourne</lastname>
<deleted />
<status>Active</status>
</user>
...
</users> |
| For such picklist fields, set the <value> element in your request to appropriate integer value from one of the <user_id> elements in the response above. |
| |
Update a Record
|
| Updating a record of a Custom Object is achieved via a HTTP POST request to the following URI. |
| |
| PUT /{api_prefix}/{id} |
| Updates a single record whose integer ID is {id}. {api_prefix} is the value of the <api_prefix> element in the API response to GET /object API request. |
| |
| REQUEST |
<custom_object>
<fields>
<field>
<name>field_3005</name>
<value>Save document as CSV file</value>
</field>
<field>
<name>field_3006</name>
<value>We have received requests from many customers to allow them to save the file as a CSV file so that they can import into other software.</value>
</field>
<field>
<name>field_3007</name>
<value>2</value>
</field>
<field>
<name>field_3009</name>
<value>1</value>
</field>
...
</fields>
</custom_object> |
| |
| RESPONSE |
| Status: 200 |
| If the record is not updated, a response other than "200" will be sent, usually along with an error message in XML format. |
| |
| In order to construct the request, you'll need a list of all available fields for the Record resource. You can retrieve this list using the Retrieve Field List and Retrieve User List techniques described above under Create a Record section. |
| |
Delete a Record
|
| Deleting a record of a Custom Object is achieved via a HTTP DELETE request to the following URI. |
| |
| DELETE /{api_prefix}/{id} |
| Deletes a single record whose integer ID is {id}. {api_prefix} is the value of the <api_prefix> element in the API response to GET /object API request. |
| |
| RESPONSE |
| Status: 200 |
| If the record is not deleted, a response other than "200" will be sent, usually along with an error message in XML format. |
