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

Name
Content-Type
Typ
string
Beschreibung
Must be set to application/json
Name
Authorization
Typ
string
Beschreibung
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
name
Typ
string
Beschreibung
Contact's full name or display name
Name
email
Typ
string
Beschreibung
Valid email address
Name
phone
Typ
string
Beschreibung
Phone number with country code (without + sign, e.g., 911234567890)
Name
whatsApp
Typ
string
Beschreibung
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
name
Typ
string
Beschreibung
Contact's full name or display name
This is the primary identifier for the contact in your list.
Name
email
Typ
string
Beschreibung
Valid email address
Must be a properly formatted email address. This field is required for all contacts.
Name
phone
Typ
string
Beschreibung
Phone number with country code
Optional field. Include the country code without the + sign (e.g., 911234567890 for India).
Name
whatsApp
Typ
string
Beschreibung
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:

Name
status
Typ
string
Beschreibung
Will be "success" for successful operations
Name
data
Typ
null
Beschreibung
Will be null for this endpoint
Name
errors
Typ
null
Beschreibung
Will be null when there are no errors

Error Response

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

Name
status
Typ
string
Beschreibung
Will be "error" for failed operations
Name
data
Typ
null
Beschreibung
Will be null when an error occurs
Name
errors
Typ
array
Beschreibung
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.