Manage Contacts

GET /v1/campaigns/{id}/contact-lists

Retrieve all contact lists belonging to a campaign.

Authentication:Header X-Api-Key(scope: campaign). Kong dual-auth: prioritize X-Tenant-IDheader, fallback query DB by Authorization key.

Base URL:Dev: https://xapi-dev.alohub.vn|  Prod: https://xapi.alohub.vn

Parameters

Request Body

Sample Code

curl -X GET "https://xapi.alohub.vn/v1/campaigns/1042/contact-lists" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

const axios = require('axios');
const response = await axios.get(
  '{{host}}/api/v1/campaigns/{{id}}/contact-lists',
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
response = requests.get(
    '{{host}}/api/v1/campaigns/{{id}}/contact-lists',
    headers=headers
)
print(response.json())

Response 200

{
  "success": "1",
  "totalRecord": 2,
  "data": [
    {
      "listId": 501,
      "listName": "Danh sach thang 4",
      "contactCount": 150
    },
    {
      "listId": 502,
      "listName": "Default List",
      "contactCount": 30
    }
  ]
}

Response Fields

Error Codes

Rate Limit Headers

GET /v1/campaigns/{id}/contact-lists/{listId}/contacts

Retrieve the list of contacts in a contact list — with pagination.

Authentication:Header X-Api-Key(scope: campaign). Kong dual-auth: prioritize X-Tenant-IDheader, fallback query DB by Authorization key.

Base URL:Dev: https://xapi-dev.alohub.vn|  Prod: https://xapi.alohub.vn

Parameters

Request Body

Sample Code

curl -X GET "https://xapi.alohub.vn/v1/campaigns/1042/contact-lists/501/contacts?page=0&size=20" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

const axios = require('axios');
const response = await axios.get(
  '{{host}}/api/v1/campaigns/{{id}}/contact-lists/{{listId}}/contacts?page=0&size=20',
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

params = {"page": "0", "size": "20"}
headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
response = requests.get(
    '{{host}}/api/v1/campaigns/{{id}}/contact-lists/{{listId}}/contacts',
    headers=headers, params=params
)
print(response.json())

Response 200

{
  "success": "1",
  "totalRecord": 150,
  "data": [
    {
      "contactId": 88001,
      "customerId": 55001,
      "phoneNumber": "0901234567",
      "name": "Nguyen Van A",
      "processStatus": 0,
      "callStatus": null
    }
  ]
}

Response Fields

Error Codes

Rate Limit Headers

POST /v1/campaigns/{id}/contacts

Add a contact to the campaign. Do not pass listId → use the first list. If there is no list → create a Default List.

Authentication:Header X-Api-Key(scope: campaign). Kong dual-auth: prioritize X-Tenant-IDheader, fallback query DB by Authorization key.

Base URL:Dev: https://xapi-dev.alohub.vn|  Prod: https://xapi.alohub.vn

Parameters

Request Body

{
  "phoneNumber": "0901234567",
  "name": "Nguyen Van A",
  "listId": 501
}

Sample Code

curl -X POST "https://xapi.alohub.vn/v1/campaigns/1042/contacts" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"0901234567","name":"KH A"}'

# Truyền listId cụ thể
curl -X POST "https://xapi.alohub.vn/v1/campaigns/1042/contacts" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"0901234567","listId":501}'

const axios = require('axios');
const response = await axios.post(
  '{{host}}/api/v1/campaigns/{{id}}/contacts',
  {
  "phoneNumber": "0901234567",
  "name": "Nguyen Van A",
  "listId": 501
},
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
payload = {
    "phoneNumber": "0901234567",
    "name": "Nguyen Van A",
    "listId": 501
}
response = requests.post(
    '{{host}}/api/v1/campaigns/{{id}}/contacts',
    json=payload,
    headers=headers
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "Contact added to list 501"
}

Response Fields

Error Codes

Rate Limit Headers

POST /v1/campaigns/{id}/contacts/bulk

Import bulk contacts (async). Return job_id immediately — the frontend must poll GET /contacts/import/{job_id}. Contacts with duplicate phone numbers are skipped (count duplicateRows, not an error).

Authentication:Header X-Api-Key(scope: campaign). Kong dual-auth: prioritize X-Tenant-IDheader, fallback query DB by Authorization key.

Base URL:Dev: https://xapi-dev.alohub.vn|  Prod: https://xapi.alohub.vn

Parameters

Request Body

{
  "listName": "Danh sach thang 4",
  "contacts": [
    {
      "phoneNumber": "0901000001",
      "name": "KH 1"
    },
    {
      "phoneNumber": "0901000002"
    }
  ]
}

Sample Code

curl -X POST "https://xapi.alohub.vn/v1/campaigns/1042/contacts/bulk" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310" \
  -H "Content-Type: application/json" \
  -d '{"listName":"DS thang 4","contacts":[{"phoneNumber":"0901000001"},{"phoneNumber":"0901000002"}]}'

const axios = require('axios');
const response = await axios.post(
  '{{host}}/api/v1/campaigns/{{id}}/contacts/bulk',
  {
  "listName": "Danh sach thang 4",
  "contacts": [
    {
      "phoneNumber": "0901000001",
      "name": "KH 1"
    },
    {
      "phoneNumber": "0901000002"
    }
  ]
},
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
payload = {
    "listName": "Danh sach thang 4",
    "contacts": [
        {
            "phoneNumber": "0901000001",
            "name": "KH 1"
        },
        {
            "phoneNumber": "0901000002"
        }
    ]
}
response = requests.post(
    '{{host}}/api/v1/campaigns/{{id}}/contacts/bulk',
    json=payload,
    headers=headers
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "Bulk import started",
  "job_id": 5,
  "total_rows": 2
}

Response Fields

Error Codes

Rate Limit Headers

GET /v1/campaigns/{id}/contacts/import/{job_id}

Poll the status of the bulk import job. The frontend polls every 2-3 seconds until status = done or failed. job_id exists in RAM — server restart will lose it.

Authentication:Header X-Api-Key(scope: campaign). Kong dual-auth: prioritize X-Tenant-IDheader, fallback query DB by Authorization key.

Base URL:Dev: https://xapi-dev.alohub.vn|  Prod: https://xapi.alohub.vn

Parameters

Request Body

Sample Code

# Poll mỗi 2-3 giây
curl -X GET "https://xapi.alohub.vn/v1/campaigns/1042/contacts/import/5" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

const axios = require('axios');
const response = await axios.get(
  '{{host}}/api/v1/campaigns/{{id}}/contacts/import/{{job_id}}',
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
response = requests.get(
    '{{host}}/api/v1/campaigns/{{id}}/contacts/import/{{job_id}}',
    headers=headers
)
print(response.json())

Response 200

{
  "jobId": 5,
  "status": "processing",
  "totalRows": 100,
  "processedRows": 42,
  "failedRows": 0,
  "duplicateRows": 1
}

Response Fields

Error Codes

Rate Limit Headers

DELETE /v1/campaigns/{id}/contacts/{contactId}

Delete a contact from the campaign. Can only delete contacts with processStatus=0 (pending). Contacts that are calling (1) or have been processed (2) cannot be deleted.

Authentication:Header X-Api-Key(scope: campaign). Kong dual-auth: prioritize X-Tenant-IDheader, fallback query DB by Authorization key.

Base URL:Dev: https://xapi-dev.alohub.vn|  Prod: https://xapi.alohub.vn

Parameters

Request Body

Sample Code

curl -X DELETE "https://xapi.alohub.vn/v1/campaigns/1042/contacts/88001" \
  -H "X-Api-Key: sk_live_xxx" \
  -H "X-Tenant-ID: 20260310"

const axios = require('axios');
const response = await axios.delete(
  '{{host}}/api/v1/campaigns/{{id}}/contacts/{{contactId}}',
  { headers: { 'Authorization': '{{api-key}}', 'X-Tenant-ID': '{{tenant-id}}', 'Content-Type': 'application/json' } }
);
console.log(response.data);

import requests

headers = {"Authorization": "{{api-key}}", "X-Tenant-ID": "{{tenant-id}}", "Content-Type": "application/json"}
response = requests.delete(
    '{{host}}/api/v1/campaigns/{{id}}/contacts/{{contactId}}',
    headers=headers
)
print(response.json())

Response 200

{
  "success": "1",
  "error_code": "SUCCESS",
  "error_message": "Contact deleted successfully"
}

Response Fields

Error Codes

Rate Limit Headers