API Reference
Start typing to search…

Subscribe Phone Numbers API

The Subscribe API enables registration of phone numbers for receiving text messages. Numbers can be supplied as an array via JSON or through a base64-encoded CSV file.

URL

POST: https://api.wknd.ai/text/subscribe

Endpoint : Subscribe via JSON or Base64 CSV

Request Headers

The following are used for authentication/authorization checks.

  • X-Client-ID: 32-byte hashed string provided by Wunderkind
  • X-Client-Secret: 64-byte hashed string provided by Wunderkind
  • Content-Type: application/json

Body Parameters

Model:

{
  "phone_numbers": {
    "phone_numbers": [
      "+12017712013",
      "+12125551234"
    ]
  },
  "csv_file": "cGhvbmVfbnVtYmVycworMTEyMzQ1Njc4OTAKKzE5ODc2NTQzMjEw",
  "sendPurpose": "test_optin"
}

phone_numbers - (optional) an array of strings.

  • Each phone number must be in E.164 format. e.g. ["+11234567890", "+19876543210"]
  • This field can be empty if csv_file is specified.

csv_file - (optional) a CSV file containing phone numbers.

  • The file must be encoded in base64 before sending
  • The CSV file must have a header phone_numbers
  • Each phone number must be in E.164 format
  • This field can be empty if phone_numbers is specified

SendPurpose - (Required) string

  • Purpose Descriptor (e.g: "test_optin", "batch_optin")

Either phone_numbers (maximum 5,000 phone numbers) or csv_file (maximum 50,000 phone numbers) must be specified.

At least one of phone_numbers or csv_file is required.

Example Using phone_numbers

{
  "phone_numbers": {
    "phone_numbers": [
      "+12017712013",
      "+12125551234"
    ]
  },
  "sendPurpose": "test_optin"
}

Example Using Base64 CSV

CSV before encoding:

+12017712013
+12125551234

Base64-encoded:

{
  "csv_file": "cGhvbmVfbnVtYmVycw0KKzEyMDE3NzEyMDEzDQorMTIxMjU1NTEyMzQ=",
  "sendPurpose": "test_optin"
}

Responses

Success Response (200)

Model:

{
  "message": "We have received and are processing your request",
  "invalidPhoneNumbers": [],
  "failedToProcessNumbers": []
}
  • message – confirmation that request was received
  • invalidPhoneNumbers – list of numbers in invalid format
  • failedToProcessNumbers – list of numbers that could not be processed

Error Response

Model

{
  "code": 0,
  "message": "string",
  "details": []
}

Error Codes

  • 401 – Unauthorized
  • 403 – Forbidden
  • 429 – Denied (exceeded limits)
  • 4XX – Bad Request
  • 5XX – Internal Server Error

Examples

Request with phone_number:

curl -X POST \ 
'https://api.wknd.ai/text/subscribe' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
  "phone_numbers": {
    "phone_numbers": ["+12017712013", "+12125551234"]
  },
  "sendPurpose": "test_optin"
}'

Response

{
  "message": "We have received and are processing your request",
  "invalidPhoneNumbers": [],
  "failedToProcessNumbers": []
}

Request with csv_file:

curl -X POST 'https://api.wknd.ai/text/subscribe' \
-H 'Content-Type: application/json' \
-H 'X-Client-ID: ********s19bvx18vly70bk5********' \
-H 'X-Client-Secret: ********c2a4b82f10f8a137b1b056c6f3f3909ddc062a6fb6b4826c********' \
-d '{
  "csv_file": "cGhvbmVfbnVtYmVycw0KKzEyMDE3NzEyMDEzDQorMTIxMjU1NTEyMzQ=",
  "sendPurpose": "test_optin"
}'

Response

{
  "message": "We have received and are processing your request",
  "invalidPhoneNumbers": [],
  "failedToProcessNumbers": []
}

Endpoint: Subscribe via CSV File Upload

POST: https://api.wknd.ai/text/csv/subscribe

Request Headers

  • X-Client-ID: 32-byte hashed string provided by Wunderkind
  • X-Client-Secret: 64-byte hashed string provided by Wunderkind
  • Content-Type: multipart/form-data

Multipart Form Fields

Example CSV

phone_numbers
+12017712013
+12125551234
+441234567890

Example cURL

curl -X POST 'https://api.wknd.ai/text/csv/subscribe' \
-H 'X-Client-ID: <your-client-id>' \
-H 'X-Client-Secret: <your-client-secret>' \
-F '[email protected]' \
-F 'send_purpose=test_optin'

Success Response (200)

{
  "message": "We have received and are processing your request",
  "invalidPhoneNumbers": [],
  "failedToProcessNumbers": []
}
  • invalidPhoneNumbers: Array. Numbers with invalid format.
  • failedToProcessNumbers: Array. Numbers that could not be processed.

Error Response

{
  "code": 0,
  "message": "string",
  "details": []
}

Error Codes

  • 401 – Unauthorized
  • 403 – Forbidden
  • 429 – Denied (exceeded limits)
  • 4XX – Bad Request
  • 5XX – Internal Server Error