Note: Messaging campaigns are an add-on, currently in closed Beta. If campaigns are not enabled for your account, contact your TalentLynk account manager to purchase credits and enable the feature.
This guide walks through creating, preparing, launching, and monitoring a messaging campaign via the API.
1. Before you start
You will need a TalentLynk user API key belonging to the user who will be campaign owner/manager.
⢠Ask your TalentLynk administrator or integration partner for the API key.
⢠Store it in a secure place, do not log, expose or share it publicly.
⢠Make sure the associated user has permission to manage campaigns.
The production API URL is https://api.talentlynk.ai.
All requests use Bearer authentication:
Authorization: Bearer tk_...
Content-Type: application/json
API responses use a standard envelope. The requested resource or operation results are returned under data.
2. Get the user and sending numbers
Start by retrieving the current user and the phone numbers available for sending:
curl "https://api.talentlynk.ai/v1/public/me" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY"
Each phone number includes:
⢠id: Use this as phoneNumberId when creating the campaign.
⢠number: The sending number in international format.
⢠name and type: Information to help identify the number.
⢠whatsappEnabled: Whether the number can send WhatsApp messages.
For a WhatsApp campaign, select a number where whatsappEnabled is true.
3. Create or resolve contacts
Create contacts before adding them to a campaign:
curl -X POST "https://api.talentlynk.ai/v1/public/contacts" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY" \
-H "Content-Type: application/json" \
-d '[{"type":"candidate","firstName":"Jane","lastName":"Doe","phoneNumber":"+447700900456"}]'
Each successful result contains data.contactId, which is the ID needed for adding the corresponding contacts to the campaign in step 6.
4. Select a WhatsApp template
Skip this step for SMS campaigns.
Retrieve the available WhatsApp templates:
curl "https://api.talentlynk.ai/v1/public/whatsapp/templates" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY"
Select a template where status is APPROVED. Save its id, body, and bodyParams for the campaign request. Templates with any other status cannot be sent.
5. Create the campaign
curl -X POST "https://api.talentlynk.ai/v1/public/campaigns" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name":"Software Engineer Outreach",
"messages":[{
"channel":"sms",
"phoneNumberId":"660aa203a316d954a555e42c",
"body":"Hi {{1}}, this is {{2}} from {{3}}.",
"bodyParams":[
{"type":"text","key":"contactFirstName","fallback":"there"},
{"type":"text","key":"userFirstName"},
{"type":"text","key":"userCompany"}
]
}]
}'
The campaign name is for internal use only; recipients will not see it.
For WhatsApp, set channel to whatsapp and include the approved template's templateId, body, and bodyParams. The selected phoneNumberId must belong to a WhatsApp-enabled number.
Save the id returned in the campaign response.
6. Add and review contacts
Add the contact IDs returned by the contacts endpoint:
curl -X POST "https://api.talentlynk.ai/v1/public/campaigns/$CAMPAIGN_ID/contacts" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactIds":["65aed368d670272d74a2c491"]}'
Review the added, skipped, error, and details fields in the response.
Review the campaign and its contacts before launch:
GET /v1/public/campaigns/{campaignId}
GET /v1/public/campaigns/{campaignId}/contactsContacts with multiple valid numbers include those numbers in the contact details.
Change the selected number when needed:
PATCH /v1/public/campaigns/{campaignId}/contacts/{campaignContactId}You can also update the campaign name, message, owner, or status while it is in draft or pending state:
PATCH /v1/public/campaigns/{campaignId}
7. Mark the campaign as pending and launch
When the campaign is ready, change its status to pending:
curl -X PATCH "https://api.talentlynk.ai/v1/public/campaigns/$CAMPAIGN_ID" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"pending"}'
Launch the campaign:
curl -X POST "https://api.talentlynk.ai/v1/public/campaigns/$CAMPAIGN_ID/send" \
-H "Authorization: Bearer $TALENTLYNK_API_KEY"
Launching starts messaging immediately and disables campaign editing. The response confirms that sending has started; processing continues asynchronously.
Important:
⢠Review the sending number, message preview, template, and contacts carefully before launching.
⢠Make sure recipients are expecting communications from you to prevent messages or numbers being reported as spam or blocked.
⢠SMS sent to US numbers must use an approved 10DLC US number.
⢠Launch will fail if the account has insufficient messaging credits.
8. Monitor and manage campaigns
Retrieve the campaign to monitor its overall status:
GET /v1/public/campaigns/{campaignId}Campaigns progress from pending to active, then finished or error.
Retrieve near real-time statistics:
GET /v1/public/campaigns/{campaignId}/statsStatistics include total, active, and removed contacts, plus sent, delivered, read, replied, and failed messages. Read statistics apply to WhatsApp only.
Use the following endpoints for ongoing management:
⢠GET /v1/public/campaigns lists campaigns. Filter by status or ownerId when needed.
⢠GET /v1/public/campaigns/{campaignId}/contacts lists contact status and activity.
⢠PATCH /v1/public/campaigns/{campaignId}/contacts/{campaignContactId} changes a contact's number or Active/Removed status.
⢠DELETE /v1/public/campaigns/{campaignId}/contacts/{campaignContactId} deletes a campaign contact.
⢠DELETE /v1/public/campaigns/{campaignId} deletes a draft or pending campaign.
New contacts can be added to finished campaigns. Launching the campaign again sends only to active contacts who have not already received its message.
Rate limits and errors
Respect the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers. After a 429 response, wait for the number of seconds supplied in Retry-After before retrying.
For validation or launch errors, read the response's data.message field, correct the request, and try again.