API Integration Documentation

Use this API endpoint to programmatically add contacts to your contact list from your backend application.

Generate your API key from Settings > API section. For security, whitelist your backend system's IP address. Include the API key in the Authorization header of your requests.

POST/external/contact-list/v1/:listId/add

Add Contacts to List

This endpoint allows you to add one or more contacts to a specific contact list. You must provide an array of contact objects, where each contact contains their information.

API Endpoint

POST https://api.oblic.app/external/contact-list/v1/{listId}/add

Replace {listId} with your actual contact list ID (e.g., a459be9e-e6e5-11f0-967f-0af3f8fe5ae7).

Request Headers

Nome
Content-Type
Tipo
string
Descrição
Must be set to application/json
Nome
Authorization
Tipo
string
Descrição
Bearer token with your API key: Bearer YOUR_API_KEY

Request Body

The request body must be an array of contact objects. Each contact object has the following properties:

Nome
name
Tipo
string
Descrição
Contact's full name or display name
Nome
email
Tipo
string
Descrição
Valid email address
Nome
phone
Tipo
string
Descrição
Phone number with country code (without + sign, e.g., 911234567890)
Nome
whatsApp
Tipo
string
Descrição
WhatsApp number with country code (without + sign, e.g., 911234567890)

Request

POST

/external/contact-list/v1/:listId/add

curl -X POST 'https://api.oblic.app/external/contact-list/v1/a459be9e-e6e5-11f0-967f-0af3f8fe5ae7/add' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '[
    {
      "name": "John Doe",
      "email": "user@example.com",
      "phone": "911234567890",
      "whatsApp": "911234567890"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "919876543210",
      "whatsApp": "919876543210"
    }
  ]'

Success Response (200)

{
  "status": "success",
  "data": null,
  "errors": null
}

Error Response (400/401/500)

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "cd": "INVALID_EMAIL",
      "message": "Invalid email address provided"
    }
  ]
}

Field Descriptions

Below is a detailed description of each field in the contact object:

Nome
name
Tipo
string
Descrição
Contact's full name or display name
This is the primary identifier for the contact in your list.
Nome
email
Tipo
string
Descrição
Valid email address
Must be a properly formatted email address. This field is required for all contacts.
Nome
phone
Tipo
string
Descrição
Phone number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890 for India).
Nome
whatsApp
Tipo
string
Descrição
WhatsApp number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890). This enables WhatsApp messaging capabilities for the contact.

Response Format

The API returns a consistent response format for both successful and failed requests.

Success Response

When contacts are successfully added, you'll receive a 200 status code with:

Nome
status
Tipo
string
Descrição
Will be "success" for successful operations
Nome
data
Tipo
null
Descrição
Will be null for this endpoint
Nome
errors
Tipo
null
Descrição
Will be null when there are no errors

Error Response

When an error occurs (status codes 400, 401, or 500), you'll receive:

Nome
status
Tipo
string
Descrição
Will be "error" for failed operations
Nome
data
Tipo
null
Descrição
Will be null when an error occurs
Nome
errors
Tipo
array
Descrição
An array of error objects, each containing a cd (error code) and message field

Success Example

{
  "status": "success",
  "data": null,
  "errors": null
}

Error Example

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "cd": "INVALID_EMAIL",
      "message": "Invalid email address provided"
    }
  ]
}

Best Practices

✓ Use Batch Operations

Since the API accepts an array of contacts, you can add multiple contacts in a single request to reduce API calls and improve performance.

✓ Validate Data Before Sending

Always validate email addresses and phone numbers in your application before making API requests to avoid unnecessary errors.

✓ Secure Your API Key

Never expose your API key in client-side code. Always make API calls from your backend server and whitelist your server's IP address.

✓ Handle Errors Gracefully

Implement proper error handling in your application to manage failed requests and provide meaningful feedback to users.