Add Contacts to Campaign by Phone Numbers

Add contacts to campaign

URL: https://icc-api.stringee.com/v1/customcampaign/add-by-phones

HTTP method: POST

Content-Type: application/json

Custom HTTP header: Name: X-STRINGEE-AUTH Value: JSON web token (JWT), see Authentication

POST data (body):

{
    "campaign_id": "CAMPAIGN_ID",
    "phones": ["PHONE_NUMBER_1", "PHONE_NUMBER_2"]
}

Field	Type	Require	Description
campaign_id	String	Yes	ID of the campaign to add contacts to
phones	String[]	Yes	List of phone numbers to add

Phone number normalization: The system automatically normalizes all phone numbers to Vietnam international format (84xxx). You can send phone numbers in various formats: 0901234567 → 84901234567, 84901234567 → 84901234567, +84901234567 → 84901234567, 901234567 → 84901234567. Invalid phone numbers will be returned in the invalid_phones field.

Response:

{
    "r": RESULT_CODE,
    "msg": "RESULT_MESSAGE",
    "data": {
        "total": TOTAL_VALID_PHONES,
        "added": ADDED_COUNT,
        "skipped": SKIPPED_COUNT,
        "skipped_phones": ["SKIPPED_PHONE_1", "SKIPPED_PHONE_2"],
        "invalid": INVALID_COUNT,
        "invalid_phones": ["INVALID_PHONE_1", "INVALID_PHONE_2"]
    }
}

Field	Type	Require	Description
r	Int	Yes	Result code (0 = success)
msg	String	Yes	Result message
data.total	Int	No	Total number of valid phone numbers sent
data.added	Int	No	Number of contacts successfully added
data.skipped	Int	No	Number of phone numbers skipped (already existed)
data.skipped_phones	String[]	No	List of skipped phone numbers
data.invalid	Int	No	Number of invalid phone numbers
data.invalid_phones	String[]	No	List of invalid phone numbers

Error Codes:

Code	Message	Description
0	Success	Contacts added successfully. Check data.added and data.skipped for details.
2	Missing params	Missing campaign_id or phones. Check request body.
3	Campaign not found	campaign_id does not exist or does not belong to your account.
7	All phones already exist	All phone numbers already exist in the campaign. No need to retry.
---	HTTP 401 Unauthorized	JWT is invalid or expired. Please generate a new token.

Sample request

POST /v1/customcampaign/add-by-phones HTTP/1.1
Host: https://icc-api.stringee.com
X-STRINGEE-AUTH: json_web_token
Accept: application/json

{
    "campaign_id": "CA123456",
    "phones": [
        "0901234567",
        "0912345678",
        "84987654321"
    ]
}

Sample response

{
    "r": 0,
    "msg": "Success",
    "data": {
        "total": 3,
        "added": 1,
        "skipped": 1,
        "skipped_phones": ["84901234567"],
        "invalid": 1,
        "invalid_phones": ["09123329999"]
    }
}

Sample response (all phones already exist)

{
    "r": 7,
    "msg": "All phones already exist in campaign",
    "data": {
        "total": 2,
        "added": 0,
        "skipped": 2,
        "skipped_phones": ["84901234567", "84912345678"],
        "invalid": 0,
        "invalid_phones": []
    }
}

Sample response (missing params)

{
    "r": 2,
    "msg": "Missing params"
}

Sample response (campaign not found)

{
    "r": 3,
    "msg": "Campaign not found"
}

Sample cURL

curl --request POST \
  --url https://icc-api.stringee.com/v1/customcampaign/add-by-phones \
  --header 'content-type: application/json' \
  --header 'x-stringee-auth: <YOUR_JWT_TOKEN>' \
  --data '{
    "campaign_id": "CA7HIODJ",
    "phones": [
        "0901234567",
        "0912345678",
        "84987654321",
        "09123329999"
    ]
}'

Best Practices:

Each request should send a maximum of 1,000 phone numbers.

For larger lists, split into batches of 500–1,000 phone numbers.

Add a delay of 200–500ms between requests to avoid rate limiting.

This API is idempotent: calling the same request again will not create duplicate records. Safe to retry on network errors or timeouts.

Always check the r field in the response. Even when r: 0 (success), check data.added, data.skipped, and data.invalid for details.

Suggestions

Add Contacts to Campaign by Phone Numbers

Add contacts to campaign