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

Nombre
Content-Type
Tipo
string
Descripción
Must be set to application/json
Nombre
Authorization
Tipo
string
Descripción
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:

Nombre
name
Tipo
string
Descripción
Contact's full name or display name
Nombre
email
Tipo
string
Descripción
Valid email address
Nombre
phone
Tipo
string
Descripción
Phone number with country code (without + sign, e.g., 911234567890)
Nombre
whatsApp
Tipo
string
Descripción
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:

Nombre
name
Tipo
string
Descripción
Contact's full name or display name
This is the primary identifier for the contact in your list.
Nombre
email
Tipo
string
Descripción
Valid email address
Must be a properly formatted email address. This field is required for all contacts.
Nombre
phone
Tipo
string
Descripción
Phone number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890 for India).
Nombre
whatsApp
Tipo
string
Descripción
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:

Nombre
status
Tipo
string
Descripción
Will be "success" for successful operations
Nombre
data
Tipo
null
Descripción
Will be null for this endpoint
Nombre
errors
Tipo
null
Descripción
Will be null when there are no errors

Error Response

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

Nombre
status
Tipo
string
Descripción
Will be "error" for failed operations
Nombre
data
Tipo
null
Descripción
Will be null when an error occurs
Nombre
errors
Tipo
array
Descripción
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.