Skip to main content
API docs by Redocly

Ocelot API (1.0.0-beta2)

Download OpenAPI specification:Download

Summary:

The Ocelot API is a RESTful API that provides endpoints for contact and contact list management.

Getting Started

To get started with the Ocelot API, you need to authenticate. The base API endpoint is https://ai.ocelotbot.com/api/v1.

Visit the published Contact List endpoints list for more details and working code examples.

Contact List

The Contact List is a technical entity which groups Contacts by technical concepts and applies constrains.

The concepts are:

  • Each Contact List has a schema which defins the posible fields a Contact can have during creation. An example of a field is:

      {
    type: PhoneNumber, // The type of the field accepted by endpoint
    name: 'Phone_Number', // The name of the field used as a variable value in templates
    displayName: 'Phone Number', // The display name
    required: true, // The flag enables constrain on the value
    unique: true, // The flag enables constrain on the value
  },

  • The schema consists of default and user provided parts.

  • Default schema is

      // Contact List Default schema
  [
    {
      type: PhoneNumber,
      name: 'Phone_Number',
      displayName: 'Phone Number',
      required: true,
      unique: true,
    },
    {
      type: Email,
      name: 'Email_Address',
      displayName: 'Email Address',
      required: false,
      unique: true,
    },
    {
      type: FirstName,
      name: 'First_Name',
      displayName: 'First Name',
      required: false,
      unique: false,
    },
    {
      type: LastName,
      name: 'Last_Name',
      displayName: 'Last Name',
      required: false,
      unique: false,
    },
  ]

  • User provided part can be set while creating Contact List via providing additionalContactFields. An example is: ```javascript { type: Text, name: 'Address', displayName: 'Address, required: false, unique: false, }

Creates a contact list

Authorizations:
chatbotUuid:apiKey_basicAuth
Request Body schema: application/json
required
name
required
string (ContactList.name)
tags
Array of strings (ContactList.tag) [ items <= 50 characters ]
object (ContactList.meta)

Information about the contact list entity's metadata. It is not limited to just the source and externalId; you can also include additional fields in the metadata of the contact list entity.

Array of objects (ContactSchemaField)

Responses

Request samples

Content type
application/json
{
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "additionalContactFields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "chatbotId": "964783cd-c648-4628-8262-55dac3831d8f",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "userId": "public_api"
}

Replace contact list (lookup by name)

Reset and replace contact list data and also remove all contacts in the contact list

Authorizations:
chatbotUuid:apiKey_basicAuth
Request Body schema: application/json
required
name
required
string (ContactList.name)
tags
Array of strings (ContactList.tag) [ items <= 50 characters ]
object (ContactList.meta)

Information about the contact list entity's metadata. It is not limited to just the source and externalId; you can also include additional fields in the metadata of the contact list entity.

Array of objects (ContactSchemaField)

Responses

Request samples

Content type
application/json
{
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "additionalContactFields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "chatbotId": "964783cd-c648-4628-8262-55dac3831d8f",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "userId": "public_api"
}

Reads the contact list

Authorizations:
chatbotUuid:apiKey_basicAuth
path Parameters
contactListId
required
string

The contact list ID

Responses

Request samples 

// Replace with the actual contact list ID
const contactListId = "your-contact-list-id";

// Your credentials
// To find correct credentials visit Basic Authentication Flow page.
const username = "Your chatbot UUID"
const password = "Your ocelot API key"

// Endpoint URL
const apiUrl = "https://ai.ocelotbot.com/api/v1/contact-list";

// Encoded credentials
const base64_encoded_credentials = btoa(`${username}:${password}`);

// Fetch options
const options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${base64_encoded_credentials}`
  }
};

fetch(`${apiUrl}/${contactListId}`, options)
  .then(response => {
    if (response.ok) {
      return response.json();
    } else if (response.status === 401) {
      throw new Error('Unauthorized');
    } else if (response.status === 404) {
      throw new Error('Contact list not found');
    } else {
      throw new Error('Error occurred');
    }
  })
  .then(data => {
    // Handle the retrieved contact list data
    console.log(data);
  })
  .catch(error => {
    // Handle any errors that occurred during the request
    console.error(error);
  });

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "chatbotId": "964783cd-c648-4628-8262-55dac3831d8f",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "userId": "public_api"
}

Replace contact list

Reset and replace contact list data and also remove all contacts in the contact list

Authorizations:
chatbotUuid:apiKey_basicAuth
path Parameters
contactListId
required
string

The contact list ID

Request Body schema: application/json
required
name
required
string (ContactList.name)
tags
Array of strings (ContactList.tag) [ items <= 50 characters ]
object (ContactList.meta)

Information about the contact list entity's metadata. It is not limited to just the source and externalId; you can also include additional fields in the metadata of the contact list entity.

Array of objects (ContactSchemaField)

Responses

Request samples

Content type
application/json
{
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "additionalContactFields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "University N1",
  • "tags": [
    ],
  • "meta": {
    },
  • "chatbotId": "964783cd-c648-4628-8262-55dac3831d8f",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "userId": "public_api"
}

Deletes the contact list

Authorizations:
chatbotUuid:apiKey_basicAuth
path Parameters
contactListId
required
string

The contact list ID

Responses

Request samples 

// Replace with the actual contact list ID
const contactListId = "your-contact-list-id";

// Your credentials
// To find correct credentials visit Basic Authentication Flow page.
const username = "Your chatbot UUID"
const password = "Your ocelot API key"

// Endpoint URL
const apiUrl = "https://ai.ocelotbot.com/api/v1/contact-list";

// Encoded credentials
const base64_encoded_credentials = btoa(`${username}:${password}`);

// Fetch options
const options = {
  method: "DELETE",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${base64_encoded_credentials}`
  }
};

fetch(`${apiUrl}/${contactListId}`, options)
  .then(response => {
    if (response.ok) {
      console.log('Contact list deleted successfully');
    } else if (response.status === 401) {
      throw new Error('Unauthorized');
    } else if (response.status === 404) {
      throw new Error('Contact list not found');
    } else {
      throw new Error('Error occurred');
    }
  })
  .catch(error => {
    // Handle any errors that occurred during the request
    console.error(error);
  });

Response samples

Content type
application/json
{
  • "statusCode": 401,
  • "message": "Invalid authentication credentials",
  • "error": "Unauthorized"
}

Creates contacts in the contact lists

Authorizations:
chatbotUuid:apiKey_basicAuth
path Parameters
contactListId
required
string

The contact list ID

Request Body schema: application/json
required
Array of objects (ContactInput)

The list of contact objects to create.

Array
Array of objects (ContactField)

The field objects of contact

Array
type
required
string (ContactSchemaField.type)
Enum: "PhoneNumber" "Email" "FirstName" "LastName" "Text"
name
required
string <= 50 characters
value
required
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "contacts": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Lists contact list contacts

Authorizations:
chatbotUuid:apiKey_basicAuth
path Parameters
contactListId
required
string

The contact list ID

query Parameters
order
string (Order)
Enum: "ASC" "DESC"

The order criteria of the result set

orderBy
string (OrderBy)

The field to order result set by

limit
integer (Limit)
Default: 50

The numbers of items

skip
integer (Skip)
Default: 0

The number of items to skip before starting to collect the result set

Responses

Request samples 

// Replace with the actual contact list ID
const contactListId = "your-contact-list-id";

// Your credentials
// To find correct credentials visit Basic Authentication Flow page.
const username = "Your chatbot UUID"
const password = "Your ocelot API key"

// Endpoint URL
const apiUrl = "https://ai.ocelotbot.com/api/v1/contact-list";

// Encoded credentials
const base64_encoded_credentials = btoa(`${username}:${password}`);

// Fetch options
const options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${base64_encoded_credentials}`
  },
};

// Query params
const query = {
  limit: 100,
  skip: 0
}

fetch(`${apiUrl}/${contactListId}/contacts?${new URLSearchParams(query)}`, options)
  .then((response) => {
    if (response.ok) {
      return response.json();
    } else if (response.status === 401) {
      throw new Error('Unauthorized');
    } else if (response.status === 404) {
      throw new Error('Contact list not found');
    } else {
      throw new Error('Error occurred');
    }
  })
  .then((data) => {
    // Handle the retrieved contact list data
    console.log(data);
  })
  .catch((error) => {
    // Handle any errors that occurred during the request
    console.error(error);
  });

Response samples

Content type
application/json
{
  • "results": {
    }
}