How To Use The Rest API

Collect! Credit and Collection Software™

Page Table of Contents

* Test Environment * End-Points * Multiple Databases * Authorization * Web Sockets * See Also * Troubleshooting

Related 'How To' Tutorials

* Use The Rest API * Use The Rest API End Point - Create Records * Use The Rest API End Point - Read Records * Use The Rest API End Point - Update Records * Use The Rest API End Point - Delete Records * Use The Rest API End Point - User Interface Forms * Use The Rest API End Point - Contact Plans * Use The Rest API End Point - Reports And Letters * Use The Rest API End Point - File Upload * Use The Rest API End Point - File Download

The Collect! REST API can be used to fetch information, create and delete records, update existing records, and execute built-in functionality.

Test Environment

We have setup a test server where you can try out the basic end-points. Here, you will find the following sections:

Generating an Authorization Token
Create, Read, Update, and Delete Operations, Grouped by Database Table

Useful Note In the API, these are just a few end-points. The test server has grouped the CRUD operations by database table, so it is easier to read. See below for more information.

Genesys Dialer: This is a specific integration that was built for Genesys.
Database Table Schemas

For a list of current API endpoints, please refer to Our Demo Site.

End-Points

All end-points begin with: "/api/v1/"

Example:

https://api.yourdomain.com/api/v1/

Useful Note If you are running the API locally without a proxy server, like Apache, then you can connect to the ports directly. Typically, the above method is used.

Example:

http://192.168.0.10:40000/api/v1/auth/login
http://192.168.0.10:4001/api/v1/data

The remainder of this document will assume that you are connecting to your API Server via the Collect! Authorization Server proxied via Apache.

Multiple Databases

If you only have a single database, such as cv_masterdb, then no further action is required.

If you have multiple databases, such as cv_demodb or others, then you need to pass the database name as a Header in your requests.

HEADER: x-collect-database

VALUE: cv_{database_name}

Authorization

In order to make requests to the API Server, you first need to authenticate. This is done with the Authorization Server.

POST Type End-Point

/api/v1/auth/login

Request Body

{
  "op_id": "{Operator ID}",
  "op_password": "{Operator Password}"
}

Code	Description
{ Operator ID}	This is the Operator ID to sign in to the API with.
{Operator Password}	This is the password for the Operator.

Example

{
  "op_id": "OWN",
  "op_password": "own"
}

Response Body

The response will include a status value. 200 is good. Everything else is a failure. If the response is good, then the response will also include a result with basic information about the Operator. It will also contain the Access Token, which is needed for future requests.

{
  "status": digit,
  "result": {
    "nx_operator": {
      "op_rowid": "digit",
      "op_id": "string",
      "op_name": "string",
      "op_level": digit,
      "op_function": digit
    },
    "access_token": "string",
    "refresh_token": "string"
  }
}

Code	Description
status	This is the status result from the Authorization Server. 200 is the expected status.
result	This will contain the nx_operator record with all the fields in the schema.
access_token	This is the Bearer token to be used in future API requests.
refresh_token	This is the Bearer token to be used in future API requests.

Example

{
  "status": 200,
  "result": {
    "nx_operator": {
      "op_rowid": "1",
      "op_id": "OWN",
      "op_name": "Owner Of The Company",
      "op_level": 10,
      "op_function": 1
    },
    "access_token": "ABC213.ABC213.ABC213-ABC213",
    "refresh_token": "ABC213.ABC213.ABC213-ABC213"
  }
}

Web Sockets

Web Sockets allow for reading messages in real-time. They are primarily used for prompting. For example, if you call the Contact Plan API, and one of the Events in the plan has "Prompt to Confirm Details" enabled, then the information is passed back to the client in a web socket.

The client updates a record, or selects a value (OK, CANCEL, YES, NO, etc.), the data is submitted back to the server with the applicable web socket Job ID, then the original API request continues until it's done or another prompt comes up.

Web Sockets will be used for all prompts including Reports and System prompts.

Establishing a Web Socket Connection

Web Sockets run on the same port as the API server. If you are using a proxy, and you have configured the proxy as per our documentation, then you need to have /websocket as part of of the URI. If you are connecting to the API server directly, then you do not need the URI.

Example Connecting to Apache Proxy

wss://api.yourdomain.com/websocket

Example Connecting to the API Directly

ws://127.0.0.1:4001

The client application needs to parse the messages looking for any that match the Web Socket ID that you connected with.

If a message exists, then the client needs to act accordingly. The are several types of messages:

key
start
end
prompt

{
  "websocket-id": "{websocket-id}",
  "jobid": "{jobid}",
  "type": "{type}",
  "subtype": "{subtype}",
  "formid": "{formid}",
  "data": {
      "field": "string",
      ...
  }
}

This is a high-level description of each code. They are covered in more detail below.

Code	Description
websocket-id	This is the web socket ID created when the web socket connection was created.
jobid	This is the unique job ID for this prompt.
type	This indicates the type of message, such as start, end, or prompt.
subtype	This indicates the type of prompt, such as form, string, or date.
buttons	It not a form type prompt, then this will be an array of the buttons that a user will have to select.
formid	If a form type prompt, then this is the form ID in the database.
data	If a form type prompt, then this is the initial data for the record.

Once you connect, the socket will return the KEY message first with the socket ID.

{
  "type": "key",
  "message": "43tzLWO2RJzlxQPpsw4EOA=="
}

Sending API Call with Socket ID

Any end-points that have Web Socket capabilities will require that value in the Message parameter to be included in the Request Header. Please refer to each end-point for the name of the parameter. Typically, it will be "websocket-id"

Example for Contact Plan

{
  "plan": "REV",
  "debtor": 123,
  "websocket-id": "43tzLWO2RJzlxQPpsw4EOA=="
}

When an end-point with a websocket-id is submitted, and the server receives the submission, it will return an acknowledgment message that will be a type of Start.

{
  "websocket-id": "43tzLWO2RJzlxQPpsw4EOA==",
  "jobid": "BB384B01-4C01-4678-8D9D-63D6B53A8804",
  "type": "start"
}

Processing a Web Socket Message

If an API call had a prompt, there will be a Prompt type message in the socket stream.

Example

{
  "websocket-id": "43tzLWO2RJzlxQPpsw4EOA==",
  "jobid": "BB384B01-4C01-4678-8D9D-63D6B53A8804",
  "type": "prompt",
  "subtype": "form",
  "formid": "35d01ff2-775d-ccb4-8f53-25d36f517384",
  "data": {
      "co_type": "5",
      "co_description": "Review file...",
      "co_priority": "30",
      "co_who": "OWN",
      "co_date": "2023-01-12",
      "co_originator": "OWN",
      "co_creation_date": "2023-01-12",
      "co_creation_time": "13:28:21",
      "co_who_from": "OWN",
      "co_lock": "1024"
  }
}

See below for Prompt Types.

Submitting Messages Back to the Server

After the user/client application has answered the prompt, then the message needs to be submitted back to the server.

The data that is submitted is dependent on the prompt type. Simple button prompts will submit back the button position in the array. Form type prompts will also contain a data packet.

The return data will always contain a jobid, which came from the original message, and a value for the button that was selected. The button values will come from the form structure. Please see the section below on accessing form structures.

{
  "jobid": "BB384B01-4C01-4678-8D9D-63D6B53A8804",
  "button": 4631,
  "data": {
      "co_type": "5",
      "co_description": "Please review Sales account",
      "co_priority": "25",
      "co_who": "SAL",
      "co_date": "2023-01-13",
      "co_originator": "OWN",
      "co_creation_date": "2023-01-29",
      "co_creation_time": "13:28:21",
      "co_who_from": "OWN",
      "co_lock": "1024"
  }
}

When the server receives the submission, it will return an acknowledgment message that will be a type of End.

{
  "websocket-id": "43tzLWO2RJzlxQPpsw4EOA==",
  "jobid": "BB384B01-4C01-4678-8D9D-63D6B53A8804",
  "type": "end"
}

This indicates that the API job is now continuing until finished or another prompt comes up.

Prompt Types

Prompt Types are indicated by the SubType parameter. In the example above, the SubType is Form.

Some messages will contain the Message parameter. The value here is text to display to the end-user such as a question for the prompt.

Button

This will contain an array of 1 or more buttons. User selects a button and the value is submitted back to the server.

Useful Note The first position of the array is 0. In the below example the buttonValue for Yes is 0 and No is 1.

Example Prompt

{
  "jobid":"{jobid}",
  "type":"prompt",
  "subtype":"button",
  "message":"Do you want to proceed?",
  "buttons":["Yes","No"]
}

Example User Response

{
  "jobid":"{jobid}",
  "button": {buttonValue}
}

String

This will be a prompt requesting the end-user to enter an alpha-numeric text string.

Example Prompt

Coming Soon

Example User Response

Coming Soon

Date

This will be a prompt requesting a date. The client application must do any date validation before submitting back to the server.

Example Prompt

Coming Soon

Example User Response

Coming Soon

Form

This is the most complex option. The JSON message for this type will also contain a formid and data packet.

The formid will match up to an existing form in the database. Please refer to the section below on obtaining form information. You will need to look up the form for any other fields that may have to be filled in. You will also need the applicable values for each button.

The data structure will contain the default values for the applicable form. The end-user user then updates the values accordingly, then submits it back to the server.

Useful Note The default data in the web socket message will not contain all the fields on the form. It will only contain the non-zero/non-blank default values. Any other fields that are set by the end-user must be submitted in the data packet back to the server.

Example Prompt

{
  "jobid":"{jobid}",
  "type":"prompt",
  "subtype":"form",
  "formid":"{formid}",
  "data":{
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}"
  }
}

Example User Response

{
  "jobid":"{jobid}",
  "button": {buttonValue},
  "data":{
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}",
    "{field}":"{data}"
  }
}

Troubleshooting

If you restart your server, the PM2 services may not be running. Run the resurrect code in PowerShell.

pm2 resurrect

Each database needs to have an ENV file in the Collect\bin\CLI\config folder. If the ENV file is missing for the data base that you are attempting to connect to, you will receive an error about not being authorized.

Was this page helpful? Do you have any comments on this document? Can we make it better? If so how may we improve this page.

Please click this link to send us your comments: helpinfo@collect.org