I. Problem Statement

  Overview

For API Credentials please reach out to support at support@intelligentcontacts.com or 1-800-214-7490 Option 1

• Securely create/import new accounts and sub-accounts data;

• Automatically synchronize accounts/sub-accounts;

• Automatically synchronize Clients data;

• Securely Initiate new payments (Credit Cards and/or ACH) and/or payment plans;

• Automatically synchronize consumer-initiated transactions and payment plans;

• Receive real-time updates on configured events (webhooks);

• Securely retrieve the reporting data based on individual business needs, etc.

If you have any questions regarding the integration and use of Intelligent Negotiator API, feel free to contact us.

  Integrations

The Intelligent Negotiator API platform is incredibly easy to integrate with. We’ve built the API interface so your application could start importing your Client's data and start working with the consumers in a matter of several hours.

  Formats

We use JSON for all the requests and responses, including the errors.

  Glossary

Most of the API revolves around several important concepts:

• Clients - represents the entity (economical or logical) to whom a sub-account debt belongs. For example, Clients in our system can serve as separate practitioners for the Hospital, client debtor for Collection Agencies, etc. A master-account can have sub-accounts linked to one or multiple different Clients, so the consumer (“master account owner”) can initiate payments/pay debts for different Clients from a single place/interface;

• Account - is a representation of a patient or a debtor. In our system, we call it master-account. A master-account can have one or multiple sub-accounts;

• Sub-account - is a representation of a doctor visit or a particular debt. A master-account should contain at least one sub-account and you can add as many sub-accounts as needed throughout the master-account lifecycle;

• Payments -  a financial movement (Credit card or ACH) made within a master-account for one or more subaccounts;

• Payment plans - an option/agreement to pay for one or more subaccounts within a provided timeframe;

• Payment method - Intelligent Negotiator API supports multiple payment methods including multiple Credit Cards and ACH. You can initiate a payment or a payment plan with any payment method linked to a master-account;

• Import - the creation of a new master account and/or sub-accounts in IN API are done using the Import endpoint;

• Payments Report - All the payment transactions processed via Intelligent Negotiator (via Consumer Interface / Virtual terminal, IN API) can be retrieved by initiating a request to Reports endpoint.
  

• 
  

•   Data types

  All of the responses returned by the Intelligent Negotiator API are in the JSON format. The description of the data types encoded in a JSON response is below.

  • boolean - a boolean value true or false;

  • date - a date in the YYYY-MM-DD format;

  • datetime - a date in the ISO-8601 format;

  • float - a value corresponding to a real number using the double-precision representation;

  • integer - a value corresponding to a 64-bit unsigned integer number;

  • object - a string representing a JSON object (please refer to the RFC 4627 for more information);

  • string - a UTF-8 compatible sequence of characters.

   

    Security

  All sensitive data is encrypted using 2048-bit keys, which allows us to set a secure environment for the client. None of the sent credentials are saved within the system as plain text and are always encrypted using an asymmetric encryption algorithm. If there is something wrong with the client’s request, a 400 Bad Request error will be returned.
  We are continuously monitoring Intelligent Negotiator  API, securing it from malware attacks, and constantly updating the security layers of our infrastructure. Intelligent Negotiator  API offers you a stable and attack-proof environment where you can keep all your credentials intact, and hidden from a potential attacker.

  We recommend you to check the Intelligent Contacts SSL certificate fingerprint on every connection.

   

    Authentication

  Intelligent Negotiator APIs use the OAuth 2.0 protocol for authentication and authorization. Intelligent Negotiator supports common OAuth 2.0 scenarios such as those for the webserver, client-side, installed, and limited-input device applications.

  With the client credentials grant type, an app sends its own credentials (the Client ID and Client Secret) to an endpoint on the Authorization server that is set up to generate an access token. If the credentials are valid, the authorization server returns an access token to the client app.

  Most typically, this grant type is used when the app is also the resource owner. For example, an app may need to access a BackEnd cloud-based storage service to store and retrieve data that it uses to perform its work, rather than data specifically owned by the end-user. This grant type flow occurs strictly between a client app and the authorization server. An end-user does not participate in this grant type flow.

  OAuth2 client credentials flow:
  

• 
  

• To begin,
  1. Obtain OAuth 2.0 client credentials from the Intelligent Contacts.
  2. With your client application details request an access token from the Intelligent Contacts Authorization Server.
  
  

  1 2 3 4 5 6 7 8 9 POST /oauth/token HTTP/1.1 Content-Type: application/json Host: sso.intelligentcontacts.com Content-Length: 153 { "grant_type": "client_credentials", "client_id": "client id", "client_secret": "client secret" }

  3. Authorization server validates the credentials.
  4. If the credentials are okay, the Authorization Server will return an access token to the client. If not, an error will be returned.
  5. With the received valid access token and with the X-IC-intelligent-portal header, the client can now initiate calls to the IN API.

    Versioning

  Any incompatible changes to the API will result in incremented versions of the API, which will change the resource URLs.
  At some point, the current version will be announced as Deprecated and you will have 2 months to switch your applications to a newer version of the API. All clients will be notified of any deprecation in the API.
  New fields can be added to the current API version, at any time without preliminary warning with subsequent documentation added afterward. However, already documented fields cannot be modified or removed. Please rely solely on them.

   

    Pagination

  Most IN API routes return lists of paginated objects instead of the whole amount. The data you receive is divided into smaller chunks of data called pages.
  current_page query parameter indicates the page number, the page being the one requested. By default, this query parameter is equal to 1.
  The number of entities is limited to 50.

   

  API REFERENCE

  
  _{Query execution sequence diagram:}

• 
  

• 
  

    Import

  
  The Import endpoint is used for creating a new account.
  This endpoint does not require any preconditions, except the Authentication.

  _{Query execution sequence diagram:}

  Accounts

An account is a representation of a patient or a debtor. In our system, we call it master-account. A master-account can have one or multiple sub-accounts.

The Accounts endpoint requires the next preconditions:

• Authentication;

• Import (not required);
  Import execution is required in case if the payment action needs to be initiated for an inexistent account;

_{Query execution sequence diagram:}

  Sub-accounts

A sub-account is a representation of a doctor visit or a particular debt. A master-account should contain at least one sub-account and you can add as many sub-accounts as needed throughout the master-account lifecycle.
Sub-accounts are always subordinated to Master Accounts and also, can be subordinated to Clients;

The Sub-accounts endpoint requires the next preconditions:

• Authentication;

• Import (not required);
  Import execution is required in case if the payment action needs to be initiated for an inexistent sub-account;
  
  

_{Query execution sequence diagram:}

  Payment Method

A payment method contains reusable payment method details for creating payments (e.g., card number, card expiration date, routing number), it does not include transaction-specific information (e.g., amount, currency).
Its purpose is to store instrument details for future payments.
Intelligent Negotiator API supports multiple payment methods including multiple Credit Cards and ACH. You can initiate a payment or a payment plan with any payment method linked to a master-account;
After executing the Post Payment Method endpoint, we securely store the card information and return to you a source identifier (payment_method_id). This unique ID replaces the card number in all future payments / payment plans, removing the need to exchange sensitive payment information.
The POST Payment Method endpoint execution does not require any preconditions, except the Authentication.

_{Query execution sequence diagram:}

  Clients

A Client represents the entity (economical or logical) to whom a sub-account debt belongs.
For example, Clients in our system can serve as separate practitioners for the Hospital, client debtor for Collection Agencies, etc.
A master-account can have sub-accounts linked to one or multiple different Clients, so the consumer (“master account owner”) can initiate payments/pay debts for different Clients from a single place/interface;
The POST Clients endpoint execution does not require any preconditions, except the Authentication.

_{Query execution sequence diagram:}

  Payment

Payment is a financial movement (Credit card or ACH) made within a master-account for one or more subaccounts.

The POST Payment endpoint execution requires the next preconditions:

• Authentication;

• Import (not required);
  Import execution is required in case if the payment action needs to be initiated for an inexistent account;

• Payment Method (not required);
  This endpoint needs to be executed in order to obtain the "payment_method_id", which will be used for initiating a payment.
  Otherwise, in case if the credit card/ eCHECK information should not be saved in the system, all the payment method details can be sent directly with the payment request.
  
  

_{Query execution sequence diagram:}

  Payment Plan:

Payment Plan is used as an option/agreement to pay for one or more subaccounts within a provided timeframe.

The POST Payment plan endpoint execution requires the next preconditions:

• Authentication;

• Import (not required);
  Import needs to be executed in case if the payment action needs to be initiated for an inexistent account;

• Payment Method;
  This endpoint needs to be executed in order to obtain the "payment_method_id", which will be used for creating a payment plan.

Important! By default, a plan is not active after creating it. To activate it, the Activate endpoint needs to be executed.
Only after activating the payment plan can be considered started and automatic payments will be processed.

_{Query execution sequence diagram:}

  Reports

Payments is a report which reflects information about all the executed payment transactions (account number, amount, balance, .etc.).
The GET Payments endpoint execution does not require any preconditions, except the Authentication.

_{Query execution sequence diagram:}

  Webhooks

The IN Webhooks allows you to subscribe to events happening in your Intelligent Negotiator account from IN Admin Interface. Depending on Client needs rather than receiving once per day an sFTP report with data that has changed, the Client can configure a subscription to IN API supported events and so receive the update each time when the configured event will occur. For example, if you need to receive an update each time when a master account data Is updated by the Consumer via consumer interface, or by the Client Agents/Admins via IN admin interface, you will create an authorization method to allow or APP to authorize on your side and will configure the Master Account changed webhook event.

You can configure the webhook events in your Intelligent Negotiator Admin interface by following the steps detailed below:

1. Navigate to Webhooks configuration Menu by logging in to Intelligent Negotiator with your Admin credentials (Settings → Webhooks).
2. Configure the Authorization method supported by your APP API (Settings → Webhooks → Access Setup tab) in order to authorize the IN Webhook requests in your API. At this stage, our Webhook builder will allow you to use only two authentication methods, Basic access authentication, or API Key authentication.

Field Name	Required	Possible Value(s)	Purpose
Authentication Key Name	Y	Depends on the client’s API. Up to 300 symbols.	Identification of the Access.
API Name	Y	Depends on the client’s API. Up to 300 symbols.	Identification of the API (in case the Client will send the webhooks to a different API).
Client ID	Y	Depends on the client’s API. Up to 300 symbols.	Authentication on the Client API side in order to be able to send the webhooks.
Client Secret	Y	Depends on the client’s API. Up to 300 symbols.	Authentication on the Client API side in order to be able to send the webhooks.

Field Name	Required	Possible Value(s)	Purpose
Authentication Key Name	Y	Depends on client’s API. Up to 300 symbols.	Identification of the Access.
API Name	Y	Depends on client’s API. Up to 300 symbols.	Identification of the API (in case the Client will send the webhooks to different API).
API Key	Y	Depends on client’s API. Up to 300 symbols.	Authentication on Client API side in order to be able to send the webhooks.
Chose Authentication Transfer method		Header / Body	Define where the authentication credentials will be included in the API call.

3. Configure the Webhooks you want to subscribe to by accessing the Settings → Webhooks → Webhooks Tab.

3.1. Select the request method GET/POST/PUT/DELETE.
3.2. Select the event you want to subscribe to (Choose an event: ).
3.3. Select the authorization method from the one that you have already configured (Choose an access setup: ).
3.4. Enter the target URL of your API, where the configured webhook request needs to be sent.
3.5. Click on Add new webhook button to save the newly configured webhook.
3.6. Go to your Sandbox/Production environment and perform a change for the newly configured webhook. (Ex. If you have configured the webhook for Master Account changed event, go to your Intelligent Negotiator Admin interface, and change the data for a test master account.
3.7. Navigate to the Webhooks logs tab and see the logs.
3.8. If no errors will be received, go to your APP/System and double-check the master account that you have just updated.

Field Name	Required	Possible Value(s)	Purpose
Choose a request method	Y	GET/POST/PUT/DELETE	RESTful API supported verbs
Choose an event	Y	Master Account changed Master Account deleted Payment initiated Payment Plan created Payment Plan changed Payment Plan canceled	Intelligent Negotiator supported Events that will trigger the Webhook.
Choose an Access Setup	Y	One of the access configured in the Access Setup menu.	Authorization on Client-side so Client APP to be able to authorize the request and receive data.
Enter a target URL:	Y	CLIENT APP/API URL	Address of the Client APP.

 

4. Review the Webhook Logs (Settings → Webhooks → Webhook Logs tab) and make sure that the new configured event is working.

Errors

During any request or flow originating, a corresponding error may be returned by API. In order to standardize errors while still giving some degree of freedom in explaining an error callback parameters should include both error_class and error message. Error message serves the purpose of communicating the issue, whereas error class should be used by the Client in order to be able to handle various scenarios.

This list may and will be extended over time:

Class	Code	Description

Class	Code	Description
BadRequest	400	Request format is wrong. Details are stored in error message.
Unauthorized	401	Authentication failed or user does not have permissions for requested operation.. More in error message.
Forbidden	403	Access denied. More in error message.
NotFound	404	Resource was not found. More in error message.
MethodNotAllowed	405	Requested method is not supported for resource.
Conflict	409	The request can't be processed due to conflicts. More in error message.
UnprocessableEntity	422	The request can't be processed due to due to semantic errors. More in error message.
InternalServerError	500	Something went wrong on our side. You can report this behaviour, but most probably our developers have already started working on it.