API Reference

by Christina Moore Updated Aug 29, 2019

When sending JSON to the Onit API make sure to set your header to content-type: application/json. Note the lower-case 'content-type'.

Terms of Service

  • As part of our fair use policy we do not allow multi-threaded jobs against the Onit API. For example, using the Onit API to create many Records at once using multiple threads to POST concurrently. Using multiple threads to ingest Records into Onit will result in blocking or cancelling the API calls.

  • When working with pagination, no more than 80,000 rows may be requested at one time. Valid limits on the maximum number of objects per page are between 1 and 80,000. Setting a limit of 0 (limit=0) is not allowed.

  • The auth_token used to access the API should come from a user designated as an API User, not a System Admin.

Pagination

You can pass along with the URL two parameters: start= and limit= that will allow you to work with pagination of your results.

start= allows you to specify the object number from with the result set will start.

limit= allows you to specify the maximum number of objects per page (between 1 and 80,000).

Example (GET request):

http://mydomain.onit.com?auth_token=xxxxxxxxxxx&field_set=_id,name,p_field_1,p_field_2&filter=[]&start=10&limit=500

Tip: We recommend a 100 Record limit on all calls to minimize stress on the system. To make calls 100 Records at a time through all available Records use the following template:

atom_data_url = 'https://abc.onit.com/api/atom_dictionaries/xxx/atoms?auth_token='xxx'&fieldset=[xxx]&limit=100&start='+start_index.to_s 
start_index = start_index.to_i + 100

Atom Dictionaries

Get List of Apps in the Environment

Description: This endpoint returns a list of all the Apps in the environment.

Method URL
GET
https://<host>/api/atom_dictionaries.json

Get App Configuration Details


Description: This endpoint returns an object with the details of the app with this <id> number.

Method URL
GET
https://<host>/api/atom_dictionaries/<id>.json

Atoms

Get a List of Atoms

Description: This endpoint, when used without filters, returns an object with the name and _id of each atom in the corresponding app.

Method URL
GET
https://<host>/api/atom_dictionaries/<dictionary_id>/atoms.json

How to filter the results

Method URL
GET
http://<host>/api/atom_dictionaries/<dictionary_id>/atoms.json?auth_token=XXXXX&filter=<cgi escaped json filter>

For an example of the Get a List of Atoms endpoint in action see the Retrieve and Update example,  Retrieve and Approve example, and Retrieve Document IDs from DocumentFolder example.


Filter Structure (JSON)

[{"field":"<field name>","type":"<field type>","comparison":"<operator (if applicable)>","value":"<value>",}]

More Info

You can append the parameter fieldset={comma separated list of fields} to get specific fields back from the query.

Method URL
GET
http://<host>/api/atom_dictionaries/<dictionary_id>/atoms.json?auth_token=XXXXX&filter=<cgi escaped json filter>&fieldset=_id,name,p_custom_1,p_custom_2,p_custom_3


IMPORTANT NOTE: System fields _id and name do not need to be prefixed with p_ but all the custom fields do.

How to Encode the Filter

Get the filter info from a dashboard grid.

Take that JSON hash and go here to encode it: http://meyerweb.com/eric/tools/dencoder/

Then take encoded value and put as the value of filter= in the url.

Response:

{"data"=>[{"name"=>"<name>", "_id"=>"<id>"}], "success"=>true, "count"=>1}

 

Create New Atom

Description: This endpoint allows you to create new records in the corresponding app

Method URL
POST
https://<host>/api/atom_dictionaries/<dictionary_id>/atoms

For an example of the Create New Atom endpoint in action see here.

Get Atom Details


Description: This endpoint returns an object with details about an atom with this <id>

Method URL
GET
https://<host>/api/atoms/<id>.json

Update Atom

Description: This endpoint allows you to update fields in an atom with this <id>

Method URL
PUT
https://<host>/api/atoms/<id>.json

For an example of the Update Atom endpoint in action see here.


JSON Body format (field_1 and field_2 are the fields you want to update):

{
    "atom":{
        "field_1":"value_1",
        "field_2":"value_2",
    }
}

Add Documents to Attachment Field

Below is a curl command that posts a file into an attachment field named test.

curl -X PUT --header "Accept: application/json" -F "atom[p_test]=@test.txt" -F "_attachment_fields[]=atom[p_test]" -k https://jpowers.prod-local.onitcorp.com/api/atoms/59930731ed404f5dce000660.json?auth_token=XYZ123 {"success":true,"message":"Update successful"}

 

Delete Atom

Description: This endpoint allows you to delete the atom with <id> number

Method URL
DELETE
https://<host>/api/atoms/<id>.json

Change Atom Phase


Description: This endpoint allows you change the phase of an atom with this <id>

Method URL
PUT
https://<host>/api/atoms/<id>/change_state.json

Parameter: current_step=<new current step number>

Important: You must enter the NUMBER (not the NAME) of the phase that you want to set the atom to. You can retrieve this number by opening the app's builder, browsing to the Phases tab, selecting a phase, and then viewing the number that appears after Phase #.

Reopen Atom

Description: This endpoint allows you to reopen an atom with this <id>. That is to say, it changes the {{status}} variable back to "Pending"

Method URL
PUT
https://<host>/api/atoms/<id>/reopen.json

Cancel

Method URL
PUT
https://<host>/api/atoms/<id>/cancel.json

Complete

Method URL
PUT
https://<host>/api/atoms/<id>/complete.json

Get Atom History


Description: This endpoint returns a list of all history events for an atom with this <id>

Method URL
GET
https://<host>/api/atoms/<id>/histories.json

Execute Reaction

Description: This endpoint will fire a pre-existing Action on a Record.

Method URL
PUT
https://<host>/api/atoms/<id>/execute_reaction/?reaction_name=<action_name>

Name of the Action to be fired on the Record in the following format: reaction_name=<action name>

Note: The Action name may contain spaces.

Endorsements

List

Method URL
GET
https://<host>/api/atoms/<id>/endorsements.json

Get

Method URL
GET
https://<host>/api/atoms/<id>/endorsements/<id>.json

Approve

Method URL
PUT
https://<host>/api/atoms/<id>/endorsements/approve.json
Parameter
user:email (email of the user who will approve the Record)

For an example of the Approve endpoint in action see here.

Reject

Method URL
PUT
https://<host>/api/atoms/<id>/endorsements/reject.json
Parameter
user:email (email of the user who will reject the Record)

Reset

Method URL
PUT
https://<host>/api/atoms/<id>/endorsements/reset.json
Parameter
user:email (email of the user who will reset the Record)

Documents

JSON does not support files, any time the API requires an attachment, the content of the request will not be JSON. Either PUT or POST the attachment with a multi-part form. GET of a document will provide information about the document. Download of a document provides binary content data of the document.

Get

Description: This endpoint returns an object with details about an atom with this <id>

Method URL
GET
https://<host>/api/documents/<id>.json

Download

Method URL
GET
https://<host>/api/documents/<id>/download

Destroy

Method URL
DELETE
https://<host>/api/documents/<id>.json

Comments

Create

Body: (http multi-part, not json):

{:comment=>{:notify_selected=>[],:message=>"api comment",:attachment=>#<File>}}

Emails

Get All Atom Emails

Description: This endpoint returns a list of all the emails associated with one specific atom

Method URL
GET
http://<host>/api/atoms/<id>/atom_emails.json

Document Folder

Get List of Files in a Document Folder Field

Description: This endpoint returns a list of all the files in a document folder field for one specific atom

Method URL
GET
https://<host>/api/atoms/<id>/get_related_documents.json/?related_document_field=<document_folder_field_name>

For an example of the Get List of Files in a DocumentFolder Field endpoint in action see here.

Add a File to a Document Folder Field

Description: This endpoint allows you to add a file to document folder field of one specific atom

Body (http multi-part, not json):

{"document"=><File>, "_attachment_fields"=>["document"], "related_document_field"=>"<documentFolderName>", "label"=>"<document description>”}

API Response:

{"data"=>"<document id>", "success"=>true, "message"=>"Document created"}
Method URL
PUT
https://<host>/api/atoms/<id>/add_related_document.json

Delete File from a Document Folder Field

Description: This endpoint allows you to delete a file from a document folder field of one specific atom

Method URL
DELETE
https://<host>/api/atoms/<id>/get_related_documents.json/?related_document_field=<document_folder_field_name>,document=<document_id>

List Dictionary

Get

Method URL
GET
https://<host>/api/list_dictionaries/<id>.json

Create


Body:

{"list_dictionary" :
{"name" : unqiue_name_of_list_dictionary, "display_name" : display_name,
     "primary_key" : attribute_name_of_primary_key
     "truncate_data" : true_(if_truncate_existing_data),
     "overwrite" :  true (if_redefine_dictionary),
     "properties" : [{"data_type" : type_of_field,
            "name" : unique_name_of_attribute,
            "display_name" : display_name
            "required" : true if required
       }]
    }
  }
Method URL
POST
 https://<host>/api/list_dictionaries.json

Update

Method URL
PUT
https://<host>/api/list_dictionaries/<id>.json

Delete

Method URL
DELETE
https://<host>/api/list_dictionaries/<id>.json

Sync

Method URL
PUT
https://<host>/api/list_dictionaries/<id>/sync.json?atom_dictionary_id=<dictionary_id>

List Item

List

Method URL
Get
https://<host>/api/list_dictionaries/<list_id>/lists.json

Get

Method URL
GET
https://<host>/api/list_dictionaries/<list_id>/lists/<list_item_id>.json

Create

File: csv, xls, or xlsx with header row of property name and successive rows of property values

Method URL
POST
https://<host>/api/list_dictionaries/<list_id>/lists.json?file=<binary file data>

Post

Body:

{list:[{property_name: property_value},…]}

 

 

Method URL
POST
https://<host>/api/list_dictionaries/<list_id>/lists.json

Update

JSON Body: {“list”:{<attr1>:<value1>,<attr2>:<value2>}}

 

Method URL
PUT
https://<host>/api/list_dictionaries/<list_id>/lists/<list_item_id>.json

Delete

Method URL
DELETE
https://<host>/api/list_dictionaries/<list_id>/lists/<list_item_id>.json

Errors

Unauthorized

Response:

{"success":false,"error":true,"message":"Error 403, you don't have permissions for this operation."}

Operation Error

Response:

{“success”:false, “message”: “<error message>”, “errors”: {“<field1>”:”<message1>”,”<field2>”:”<message2>”}}
Next Article API Examples

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.