# OMniLeads RESTful API

## OMniLeads RESTful API

This section is intended for developers who wish to run an integration between the CRM system they maintain and OMniLeads. 

Therefore, the terminology and information presented here is intended for software developers. OMniLeads has a RESTful API based on HTTPS / JSON. The API allows access to system resources and services outside the web user interface, thus allowing external systems to easily integrate with OMniLeads. 

The authentication methods available to use this API are by Session (the agent must be logged into the system) and by Token (from the login to the API, with the parameters user and agent pass), in this case the following line must be passed in the request headers:

«Authorization: Bearer \<token obtenido>»

Example:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_token_credentials_example.png" alt=""><figcaption></figcaption></figure>

Note&#x20;

As new releases progress, this section will always be expanded as new endpoints emerge as the releases progress.&#x20;

The available endpoints are described below.

### Login Endpoint

This method provides the possibility of authenticating as a system user, and then (in case of a successful login) accessing other available endpoints depending on the user profile with which said login was performed.

**URL**: POST [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/login

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_user_login.png" alt=""><figcaption></figcaption></figure>

*figure 1: endpoint login request*

| field name | type   | description                                                             |
| ---------- | ------ | ----------------------------------------------------------------------- |
| username   | string | username del usuario generado en el menú de creación de usuarios de OML |
| password   | string | password del usuario generado en el menú de creación de usuarios de OML |

#### Successful Authentication&#x20;

If the login is successful, the method returns the following output (with option to return agent\_id in response field):

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_user_login_ok.png" alt=""><figcaption></figcaption></figure>

*figure 2: endpoint login request ok*

As you can see in the figure, a successful login returns, among other fields, a security token. This token must be used in future API requests from the authenticated user.&#x20;

In addition, the “expires\_in” field sets the lifetime of the generated token. If the system launches a request and the security token has expired, then a new authentication must be performed.

Note&#x20;

The duration of the security token is configured under the parameter “TOKEN\_EXPIRED\_AFTER\_SECONDS” in the file “/opt/omnileads/ominicontacto/ominicontacto/settings/production.py”, now available as a parameterization variable in the Ansible inventory file (inventory.yml).

#### Authentication failed

If the login is not successful, the method returns the following output:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_user_login_fail.png" alt=""><figcaption></figcaption></figure>

*figure 3: endpoint login request fail*

### Endpoint get Contact Database structure

This endpoint enables the possibility of obtaining information from the fields of a campaign's contact database. With this information, it will then be possible to create a contact. The credentials must belong to an Agent  or a Supervisor  who are associated with the campaign.

**URL**: POST [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/campaign/database\_metadata/

| field name       | type    | description                                                                                                                                                                                                                                                                             |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| idExternalSystem | integer | Optional parameter, if specified the system will try to locate the specified campaign by searching for this value as the “external\_id” of the campaign. If not specified the system will assume that the value of the “idCampaign” parameter is the internal id of the campaign in OML |
| idCampaign       | string  | Id of the campaign to which the database belongs, the meaning of its value depends on whether the “idExternalSystem” parameter is specified or not                                                                                                                                      |

If there are no errors, an output like this will be returned, with the data from the database fields:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_database_metadata.png" alt=""><figcaption></figcaption></figure>

The “fields” field indicates the list of all the fields in the database. The “main\_phone” field indicates which field corresponds to the main phone number. The “external\_id” field indicates which of the fields corresponds to the external identifier of the contact. If the database does not have an external identifier field, the “external\_id” field will have the value None.&#x20;

In case of errors, a JSON will be returned with the “status” field: “ERROR” and the details of the errors in the “errors” field. Otherwise, the value of the “status” field will be “OK”.

### Endpoint contact creation

This endpoint enables the ability to add a contact to a campaign's contact database. The credentials must belong to an Agent  or a Supervisor who is associated with the campaign.

**URL**: POST [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/new\_contact/

| field name       | type    | description                                                                                                                                                                                                                                                                             |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| idExternalSystem | integer | Optional parameter, if specified the system will try to locate the specified campaign by searching for this value as the “external\_id” of the campaign. If not specified the system will assume that the value of the “idCampaign” parameter is the internal id of the campaign in OML |
| idCampaign       | string  | Id of the campaign to which the database belongs, the meaning of its value depends on whether the “idExternalSystem” parameter is specified or not                                                                                                                                      |

In addition, the values ​​of the fields corresponding to the contact data must be sent, and their names can be obtained with the endpoint to obtain the structure of the Contact Database (Endpoint to obtain the structure of the Contact Database). It is mandatory to send a value for the field indicated as “main\_phone”, and in case the database has an external identifier field, the value of the field indicated as “external\_id” must not previously exist in another contact in the database.

If there are no errors, an output like this will be returned, with the contact data and its OML ID:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_new_contact.png" alt=""><figcaption></figcaption></figure>

If there are errors, a JSON will be returned with the field “status”:”ERROR” and the details of the errors in the field “errors”. Otherwise, the value of the “status” field will be “OK”.

### Endpoint for call generation

Allows generating calls (click to call) from an External CRM System. The credentials must belong to an Agent (Users).

**URL**: POST [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/makeCall

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_new_call_request.png" alt=""><figcaption></figcaption></figure>

*figure 4: endpoint new call request*

| field name       | type   | description                                                                                                                                                                                                                                                                                                                |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| idExternalSystem | string | It is an optional parameter, it must be sent in case you want to identify the campaign with the ID of the external CRM system.                                                                                                                                                                                             |
| idCampaign       | string | It is a mandatory parameter, it must correspond to the identifier of an OML campaign. If the parameter “idExternalSystem” is sent, it must correspond to the “external identifier” field of a Campaign associated with the indicated External System.                                                                      |
| idAgent          | string | It is a mandatory parameter, it must correspond to the identifier of an Agent in the system. If the parameter “idExternalSystem” is sent, it must correspond to the “external identifier” field of an Agent associated with the external CRM System.                                                                       |
| idContacto       | string | It is an optional parameter, if it is not sent it is assumed that it is a new contact. If sent it must correspond to the identifier of a Contact in the Campaign's contact database. If the parameter “idExternalSystem” is sent it must correspond to the field in the contact database marked as an external identifier. |

If there are errors, a JSON will be returned with the field “status”:”ERROR” and the details of the errors in the field “errors”. Otherwise, the value of the “status” field will be “OK”.

### Endpoint listing of rating options

**URL** GET [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/campaign/\<idc:integer>/dispositionOptions/ (1)

**URL** GET [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/campaign/\<idc:string>/dispositionOptions/\<ids:integer>/ (2)

This method allows you to obtain a list of the rating options available to rate a contact in a campaign.&#x20;

The credentials must belong to an Agent (Users). The parameters of this endpoint are specified in the URL. It has two ways of use, if you use variant (1), with a single parameter, the value of the parameter “idc” must be an integer specifying the internal id of an OML campaign.&#x20;

Variant (2) is to be used in the interaction from an external CRM system to OML and in this case the parameter “ids” must specify the id of the external CRM system and the parameter “idc” the identifier of a campaign in that external system. In the event that the endpoint is executed without errors, an output will be returned with a list of rating options indicating which of the options are hidden similar to the following:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_disposition_options.png" alt=""><figcaption></figcaption></figure>

If the ID of a non-existent campaign or external CRM system is not entered, an output similar to the following will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_disposition_options_not_found.png" alt=""><figcaption></figcaption></figure>

### Endpoint call disposition list

This method allows you to obtain a list of the ratings that an agent has made. The credentials must belong to an Agent (Users).

**URL**: GET [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/disposition/

If there are no errors, the list of ratings made by the agent will be returned.

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_agent_disposition_list.png" alt=""><figcaption></figcaption></figure>

### Endpoint create new rating

This endpoint enables the possibility of "rating" a transaction on a contact. When a CRM user finishes a transaction, it is normal for it to be closed with a rating, so with this method the external CRM System can impact the rating in OMniLeads. The credentials must belong to an Agent (Users).

**URL**: POST [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/disposition/

| field name          | type    | description                                                                                                                                                                                                                                                                                |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| idExternalSystem    | integer | Optional parameter, if specified the system will try to locate the specified contact by searching for this value as “external\_id” in the campaign database. If not specified the system will assume that the value of the “idContact” parameter is the internal id of the contact in OML. |
| idContact           | string  | Id of the contact to be rated, the meaning of its value depends on whether or not the “idExternalSystem” parameter is specified                                                                                                                                                            |
| idDispositionOption | integer | The id of the campaign rating option with which the contact will be rated. Each campaign defines its own rating options, see the endpoint that allows you to obtain them. The option must not be hidden.                                                                                   |
| callid              | string  | Optional parameter, the call id                                                                                                                                                                                                                                                            |
| comments            | string  | Agent's remarks in the rating                                                                                                                                                                                                                                                              |

If there are no errors, an output like this will be returned, with the data of the new qualification created:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_output.png" alt=""><figcaption></figcaption></figure>

If you try to create a new qualification instance for a contact already qualified in the campaign, the following error will be returned

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_dup.png" alt=""><figcaption></figcaption></figure>

If the contact id is not found in the campaign database, the following error message will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_contact_not_found.png" alt=""><figcaption></figcaption></figure>

If the rating option id is not found in the campaign database, or the rating option is hidden, the following error message will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_disp_opt_not_found.png" alt=""><figcaption></figcaption></figure>

### Endpoint create new contact and assign rating to it

This endpoint enables the possibility of "qualifying" a management at the same time as creating a contact, that is, the contact is created and associated with the qualification to be created. The credentials must belong to an Agent (Users).

**URL**: POST [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/new\_contact/disposition/

| field name             | type    | description                                                                                                                                                                                              |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phone                  | string  | The contact's phone number                                                                                                                                                                               |
| idExternalContact      | string  | Optional parameter, the contact id in an external CRM system                                                                                                                                             |
| idDispositionOption    | integer | The id of the campaign rating option with which the contact will be rated. Each campaign defines its own rating options, see the endpoint that allows you to obtain them. The option must not be hidden. |
| comments               | string  | Agent's remarks in the rating                                                                                                                                                                            |
| callid                 | string  | Optional parameter, the call id                                                                                                                                                                          |
| \<optional\_bd\_field> | string  | Optional parameters, values ​​can be defined to fill in the data of the contact to be created, the field names must match the fields in the campaign database.                                           |

If there are no errors, an output like this will be returned, with the data of the new qualification created:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_output.png" alt=""><figcaption></figcaption></figure>

If the rating option id is not found in the campaign database, or the rating option is hidden, the following error message will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_disp_opt_not_found.png" alt=""><figcaption></figcaption></figure>

### Endpoint to modify an existing rating

This endpoint enables the ability to modify an existing rating in OMniLeads.

Credentials must belong to an Agent (Users).

**URL**: PUT [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/disposition/\<idDisposition>

| field name          | type    | description                                                                                                                                                                                                                                                                                |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| idExternalSystem    | integer | Optional parameter, if specified the system will try to locate the specified contact by searching for this value as “external\_id” in the campaign database. If not specified the system will assume that the value of the “idContact” parameter is the internal id of the contact in OML. |
| idContact           | string  | Id of the contact to be rated, the meaning of its value depends on whether or not the “idExternalSystem” parameter is specified                                                                                                                                                            |
| idDispositionOption | integer | The id of the campaign rating option that the contact will be rated with. Each campaign defines its own rating options, see the endpoint that allows you to get them. The option should not be hidden in case the original option is changed.                                              |
| callid              | string  | Optional parameter, the call id                                                                                                                                                                                                                                                            |
| comments            | string  | Agent's remarks in the rating                                                                                                                                                                                                                                                              |

If there is no error, the following type of output will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_update_disposition.png" alt=""><figcaption></figcaption></figure>

If a non-existent rating id is specified in the URL, the following error output will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_update_disposition_err_not_found.png" alt=""><figcaption></figcaption></figure>

If you try to modify the rating instance by changing the parameters “idContact” and “idDispositionOption” and you find that there could be two ratings for the same contact in a campaign, the following error message will be displayed:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_dup.png" alt=""><figcaption></figcaption></figure>

If the contact id is not found in the campaign database, the following error message will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_contact_not_found.png" alt=""><figcaption></figcaption></figure>

If the rating option id is not found in the campaign database, or the new rating option is hidden, the following error message will be returned:

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_create_disposition_err_disp_opt_not_found.png" alt=""><figcaption></figcaption></figure>

### Agent Session API in Asterisk

API endpoints used by WebPhone through which you can control agent sessions in Asterisk.

* [API de sesión de Agente en Asterisk](/english/omnileads-restful-api/agent-session-api-in-asterisk.md)
  * [Inicio de sesión de agente en Asterisk](/english/omnileads-restful-api/agent-session-api-in-asterisk.md#inicio-de-sesion-de-agente-en-asterisk)
  * [Cierre de sesión de agente en Asterisk](/english/omnileads-restful-api/agent-session-api-in-asterisk.md#cierre-de-sesion-de-agente-en-asterisk)
  * [Ingreso en pausa de agente](/english/omnileads-restful-api/agent-session-api-in-asterisk.md#ingreso-en-pausa-de-agente)
  * [Salida de pausa de agente](/english/omnileads-restful-api/agent-session-api-in-asterisk.md#salida-de-pausa-de-agente)

### Endpoint to obtain SIP Agent credentials

Eset endpoint provides the necessary credentials to authenticate the agent on the SIP server using a WebPhone.

**URL**: GET [https:/](https://documentacion-omnileads.readthedocs.io/)/\<omnileads\_addr>/api/v1/sip/credentials/agent/

<figure><img src="https://documentacion-omnileads.readthedocs.io/es/latest/_images/api_agent_sip_credentials.png" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.omnileads.net/english/omnileads-restful-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.