Outreach

Outreach webhooks let external systems create or update contacts and optionally create applications and conversations in Tether. This guide covers the outreach webhook endpoint and the supported payload formats.

POST/api/webhook/outreach

Create contact via webhook

This endpoint creates or updates a contact in Tether from a webhook request. It is commonly used for lead forms, CRM sync, or partner integrations. If the outreach configuration includes a starter message, Tether will send it after the contact is created.

Authentication

Send the user API key in the Authorization header using the Bearer scheme.

Required attributes

Name
configurationId
Type
string
Description
The configuration ID for the outreach campaign or source.
Name
phoneNumber
Type
string
Description
The phone number of the contact (with country code).

Optional attributes

Name
firstName
Type
string
Description
The first name of the contact.
Name
lastName
Type
string
Description
The last name of the contact.
Name
email
Type
string
Description
The email address of the contact.

This example uses the raw (flat) payload format. For structured payloads with separate contact, application, and conversation objects, see the fixed format section below.

You can include additional custom key-value pairs in your request. These properties are stored and mapped into the contact, application, and conversation records.

Request

POST

/api/webhook/outreach

curl -X POST https://your-tether-instance.com/api/webhook/outreach \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "68d6d7de324658b8a1760d5e",
    "phoneNumber": "+12345671895",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }'

Success Response (200)

{
  "success": true,
  "message": "Data processed successfully and message sent.",
  "data": {
    "contactId": "507f1f77bcf86cd799439012",
    "conversationId": "507f1f77bcf86cd799439013",
    "applicationId": "507f1f77bcf86cd799439014"
  }
}

Custom properties

You can include any additional key-value pairs beyond the required fields. These custom properties will be automatically stored and propagated across the contact, application, and conversation records, making them available throughout the customer lifecycle.

Example with custom properties

Include any additional fields that are relevant to your use case, such as company name, lead source, industry, or any other custom data. Simply add them as key-value pairs at the root level of your request.

Request with custom properties

curl -X POST https://your-tether-instance.com/api/webhook/outreach \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "68d6d7de324658b8a1760d5e",
    "phoneNumber": "+12345671895",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "company": "Acme Corp",
    "industry": "Technology",
    "leadSource": "Website Form",
    "budget": "$10,000"
  }'

Fixed format payloads (contacts, applications, conversations)

Use the fixed format when you already have structured data for contacts, applications, and conversations. This format lets you create or update multiple entities in a single request.

configurationId is still required.
contacts.phoneNumber is required when sending contacts.
If both applications and conversations are provided, they are processed for the same contact.

Example: contacts + application + conversation

Use this when you have full lead data and want to create the contact, an application, and a conversation in one request.

Fixed format request

curl -X POST https://your-tether-instance.com/api/webhook/outreach \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "configurationId": "68d6d7de324658b8a1760d5e",
    "contacts": {
      "phoneNumber": "+12345671895",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    },
    "applications": {
      "status": "New"
    },
    "conversations": {
      "channelType": "sms"
    }
  }'

Best practices

Always include the country code with phone numbers (e.g., +1 for US)
Validate phone number format before sending to avoid errors
Use meaningful configuration IDs to track different lead sources
Include as much contact information as possible to improve lead quality
Implement retry logic for failed webhook requests