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

ନାମ
Content-Type
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Must be set to application/json
ନାମ
Authorization
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
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:

ନାମ
name
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Contact's full name or display name
ନାମ
email
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Valid email address
ନାମ
phone
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Phone number with country code (without + sign, e.g., 911234567890)
ନାମ
whatsApp
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
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:

ନାମ
name
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Contact's full name or display name
This is the primary identifier for the contact in your list.
ନାମ
email
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Valid email address
Must be a properly formatted email address. This field is required for all contacts.
ନାମ
phone
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Phone number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890 for India).
ନାମ
whatsApp
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
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:

ନାମ
status
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Will be "success" for successful operations
ନାମ
data
ଟାଇପ୍ କରନ୍ତୁ |
null
ବର୍ଣ୍ଣନା
Will be null for this endpoint
ନାମ
errors
ଟାଇପ୍ କରନ୍ତୁ |
null
ବର୍ଣ୍ଣନା
Will be null when there are no errors

Error Response

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

ନାମ
status
ଟାଇପ୍ କରନ୍ତୁ |
string
ବର୍ଣ୍ଣନା
Will be "error" for failed operations
ନାମ
data
ଟାଇପ୍ କରନ୍ତୁ |
null
ବର୍ଣ୍ଣନା
Will be null when an error occurs
ନାମ
errors
ଟାଇପ୍ କରନ୍ତୁ |
array
ବର୍ଣ୍ଣନା
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.