Surge API

https://docs.surge.app
Admin
The Surge API enables tighter integration with the Surge platform, allowing for enhanced customer...
Tokens:19,383
Snippets:92
Trust Score:6.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Publishable Token Example URL

Source: https://docs.surge.app/ui/home/authentication

Example URL for an embedded Surge UI component using a publishable account token. Requires 'token' and 'user_id' query parameters.

```text
https://embed.surge.app/conversations?user_id=usr_01jz3d51beesrr3zryp246cj0s&token=atok_live_7db4gv7yqw6o4opijyqes2agl4noofgjycrmufjf7mtovs5u32uwuz
```

--------------------------------

### Show User in Python

Source: https://docs.surge.app/api-reference/endpoint/users/get-user

Example of how to use the Surge Python SDK to retrieve a user by their ID. Requires initializing the Surge client with account and token credentials.

```Python
from surge import Surge

client = Surge(
  surge_account="YOUR_SURGE_ACCOUNT",
  token="YOUR_TOKEN",
)

client.users.show(
  id="usr_01j9dwavghe1ttppewekjjkfrx",
)
```

--------------------------------

### Signed Token Example URL

Source: https://docs.surge.app/ui/home/authentication

Example URL for an embedded Surge UI component using a signed user token. Requires only the 'token' query parameter as it's user-specific.

```text
https://embed.surge.app/conversations?token=eyJhbGciOiJFZERTQSIsImtpZCI6InNnbl8wMWp5bWowZ3AwZjNidmJmMmpyazRoYnd0ayIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NTA4ODkyMDgsInN1YiI6InVzcl8wMWp5bWdkZnJwZWMyYXNjNW0wejNhNmZyOSJ9.zKayo3EDrUm1Hw8URrofuYwajgyTu6dH2H0FEuRExprP1IV66FHa8wC3SfdzV7sR3AjDGAwkuAXztScq6rBnBw
```

--------------------------------

### Surge Webhook Functionality

Source: https://docs.surge.app/api-reference/webhooks/introduction

Details on how Surge webhooks work, including their purpose, setup requirements, delivery mechanisms, retry policies, and recommended best practices for integration.

```APIDOC
Webhooks:

Purpose:
  Proactively notify your application when events occur in your SMS operations, enabling real-time updates and automation.

Why use webhooks?
  - Real-time updates: receive instant notifications when things happen.
  - Automation friendly: perfect for building automated workflows.
  - Efficient: no need to poll for updates.
  - Reliable: ensure you never miss an important event.

Getting started:
1. Set up a publicly accessible HTTPS endpoint on your server.
2. Register your webhook URL in the Surge dashboard.
3. Implement handlers for the events you care about.

Webhook delivery & retries:
  - Successful delivery requires a `200 OK` or `201 Created` HTTP status code response.
  - Surge will attempt to deliver webhooks up to 20 times upon failure.
  - Retries use exponential backoff with jitter.

Best practices:
1. Make webhook handlers idempotent: receiving the same webhook multiple times should not have unintended side effects.
2. Validate webhook signatures: ensure events originate from Surge.
3. Respond to webhooks quickly: slow responses may trigger multiple delivery attempts.

Related:
  - Signature validation: [See /api-reference/webhooks/signature-validation]
```

--------------------------------

### Create Contact (Python)

Source: https://docs.surge.app/api-reference/endpoint/contacts/create

Example demonstrating how to create a new contact using the Surge Python SDK. This requires your Surge account identifier and an authentication token.

```Python
from surge import Surge

client = Surge(
    surge_account="YOUR_SURGE_ACCOUNT",
    token="YOUR_TOKEN",
)
client.contacts.create(
    first_name="Dominic",
    last_name="Toretto",
    phone_number="+18015551234",
)
```

--------------------------------

### Send a message cURL Example

Source: https://docs.surge.app/api-reference/endpoint/messages/send

Example using cURL to send a message via the Surge API, including attachments and conversation details.

```bash
curl -X POST https://api.surge.app/accounts/acct_01j9a43avnfqzbjfch6pygv1td/messages \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ \
"attachments": [ \
{ \
"url": "https://toretto.family/coronas.gif" \
} \
], \
"body": "Thought you could leave without saying goodbye?", \
"conversation": { \
"contact": { \
"first_name": "Dominic", \
"last_name": "Toretto", \
"phone_number": "+18015551234" \
} \
} \
}'
```

--------------------------------

### Python SDK: Check Verification

Source: https://docs.surge.app/api-reference/endpoint/verifications/check

Example of how to use the Surge Python SDK to check a verification code. It requires your Surge account details and a verification ID and code.

```python
from surge import Surge

client = Surge(
  surge_account="YOUR_SURGE_ACCOUNT",
  token="YOUR_TOKEN",
)

client.verifications.check(
  id="vfn_01jayh15c2f2xamftg0xpyq1nj",
  code="123456",
)
```

--------------------------------

### Send a blast cURL Example

Source: https://docs.surge.app/api-reference/endpoint/blasts/send

Demonstrates how to send a blast using cURL, including setting the Authorization header, Content-Type, and providing the request body with blast details and recipients.

```curl
curl -X POST https://api.surge.app/accounts/acct_01j9a43avnfqzbjfch6pygv1td/blasts \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ \
"attachments": [ \
{ \
"url": "https://example.com/image.jpg" \
} \
], \
"body": "Join us for our grand opening!", \
"name": "Grand Opening Announcement", \
"send_at": "2024-02-01T15:00:00Z", \
"to": [ \
"seg_01j9dy8mdzfn3r0e8x1tbdrdrf", \
"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf", \
"+18015551234", \
"+18015555678" \
] \
}'
```

--------------------------------

### Surge API - Webhook Management

Source: https://docs.surge.app/api-reference/endpoint/accounts/update

This section provides an introduction to webhooks and details on signature validation for the Surge platform. It guides users on securing webhook integrations.

```APIDOC
API Reference:

Webhooks:
  + Introduction (/api-reference/webhooks/introduction)
  + Signature validation (/api-reference/webhooks/signature-validation)

Signature validation:
  Description: Explains how to validate webhook signatures to ensure the authenticity of incoming events.
  (Specific validation steps or code examples would be listed here if available in the input text)
```

--------------------------------

### cURL Example for Updating an Account

Source: https://docs.surge.app/api-reference/endpoint/accounts/update

This snippet demonstrates how to use cURL to send a PATCH request to update an existing account, including authorization headers and a JSON payload.

```shell
curl -X PATCH https://api.surge.app/accounts/acct_01jpqjvfg9enpt7pyxd60pcmxj \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "D·T Precision Auto Shop",
"time_zone": "America/Los_Angeles"
}'
```

--------------------------------

### Message Received Webhook Payload Example

Source: https://docs.surge.app/api-reference/webhooks/events/message-received

An example JSON payload structure for the 'message.received' webhook event, detailing the data received when a message is sent to a Surge phone number.

```JSON
{
  "account_id": "acct_01japd271aeatb7txrzr2xj8sg",
  "data": {
    "id": "msg_01jav96823f9x9054d6gyzpp16",
    "body": "I don't have friends, I got family.",
    "attachments": [
      {
        "id": "att_01jav8z6x1j4m1b3w8v2jz7j3r",
        "type": "image",
        "url": "https://toretto.family/image.jpg"
      }
    ],
    "received_at": "2024-10-22T23:32:49Z",
    "conversation": {
      "id": "cnv_01jav8xy7fe4nsay3c9deqxge9",
      "phone_number": {
        "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
        "number": "+18015556789",
        "type": "local"
      },
      "contact": {
        "id": "ctc_01ja88cboqffhswjx8zbak3ykk",
        "last_name": "Dominic",
        "first_name": "Toretto",
        "phone_number": "+18015551234"
      }
    },
    "type": "message.received"
  }
}
```

--------------------------------

### Surge Conversation Embed Component

Source: https://docs.surge.app/ui/components/conversation

This section details how to embed the Surge Conversation component using different identifiers. It covers the required parameters and provides examples for each method.

```APIDOC
Surge Conversation Embed Component:

Embeds the Surge conversation component into a webpage, allowing users to view messages and send new ones. Supports embedding via Conversation ID, Contact ID, or Phone Number.

Base URL: https://embed.surge.app/conversation/

Parameters:
  - user_id: (Required) Your Surge user ID.
  - token: (Required) Your Surge account token.

Methods:

1.  Embed with Conversation ID:
    Displays a specific conversation.
    URL Structure: /conversation/{CONVERSATION_ID}
    Parameters:
      - CONVERSATION_ID: (Required) The unique ID of the conversation to display.
    Example:
      <iframe src="https://embed.surge.app/conversation/{CONVERSATION_ID}?user_id={SURGE_USER_ID}&token={ACCOUNT_TOKEN}"></iframe>

2.  Embed with Contact ID:
    Displays the conversation associated with a contact, or initiates a new one if none exists.
    URL Structure: /conversation/new?contact={CONTACT_ID}
    Parameters:
      - CONTACT_ID: (Required) The ID of the contact whose conversation should be displayed.
    Example:
      <iframe src="https://embed.surge.app/conversation/new?contact={CONTACT_ID}&user_id={SURGE_USER_ID}&token={ACCOUNT_TOKEN}"></iframe>

3.  Embed with Phone Number:
    Displays the conversation for a given phone number, or creates a new contact and conversation if none exists.
    URL Structure: /conversation/new?phone_number={PHONE_NUMBER}
    Parameters:
      - PHONE_NUMBER: (Required) The phone number of the contact.
      - FIRST_NAME: (Optional) The first name of the contact.
      - LAST_NAME: (Optional) The last name of the contact.
    Example:
      <iframe src="https://embed.surge.app/conversation/new?phone_number={PHONE_NUMBER}&first_name={FIRST_NAME}&last_name={LAST_NAME}&user_id={SURGE_USER_ID}&token={ACCOUNT_TOKEN}"></iframe>

Notes:
- The Conversation ID method is preferred for performance.
- Robust authentication options are planned for future releases.
```

--------------------------------

### Style Unread Count Component with Tailwind CSS

Source: https://docs.surge.app/ui/components/unread-count

Demonstrates how to integrate the Unread Count component within a link element, using Tailwind CSS for styling. This example positions the component in the bottom right corner and ensures it remains centered within its container.

```html
<a
  href="/messages"
  className="flex relative h-9 w-9 items-center justify-center rounded-lg bg-accent text-accent-foreground transition-colors hover:text-foreground md:h-8 md:w-8"
>
  <!-- Lucide message-circle icon -->
  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="h-5 w-5">
    <path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"></path>
  </svg>
  <span className="sr-only">Messages</span>

  <iframe
    className="-ml-1/2 pointer-events-none absolute left-2 mt-4 inline-flex h-6 min-w-6 max-w-10 scale-75"
    src="https://embed.surge.app/unread_count?user_id={SURGE_USER_ID}&token={ACCOUNT_TOKEN}"
  ></iframe>
</a>
```

--------------------------------

### Create User with Python SDK

Source: https://docs.surge.app/api-reference/endpoint/users/create

Demonstrates how to use the Surge Python SDK to create a new user. It shows client initialization and the method call with necessary parameters.

```Python
from surge import Surge

client = Surge(
  surge_account="YOUR_SURGE_ACCOUNT",
  token="YOUR_TOKEN",
)

client.users.create(
  first_name="Brian",
  last_name="O'Conner",
  metadata={"email": "boconner@toretti.family", "user_id": 1234},
  photo_url="https://toretti.family/people/brian.jpg",
)
```

--------------------------------

### Users API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoints for managing users. Includes creating new users and retrieving user information.

```APIDOC
POST /users/create
  Description: Creates a new user.
  Parameters:
    (Request Body) - User creation details.
  Returns:
    Details of the newly created user.
```

```APIDOC
GET /users/get-user
  Description: Retrieves a specific user.
  Parameters:
    userId: The unique identifier for the user.
  Returns:
    Details of the requested user.
```

--------------------------------

### Users API Endpoints

Source: https://docs.surge.app/index

Endpoints for managing users. Includes creating new users and retrieving user information.

```APIDOC
POST /users/create
  Description: Creates a new user.
  Parameters:
    (Request Body) - User creation details.
  Returns:
    Details of the newly created user.
```

```APIDOC
GET /users/get-user
  Description: Retrieves a specific user.
  Parameters:
    userId: The unique identifier for the user.
  Returns:
    Details of the requested user.
```

--------------------------------

### Token Expiring Event

Source: https://docs.surge.app/ui/home/authentication

An example of the event emitted by an embedded UI component when its authentication token is about to expire.

```json
{
  "source": "surge_inbox",
  "type": "token_expiring",
  "data": {
    "seconds_remaining": 15
  }
}
```

--------------------------------

### Message Failed Event Payload

Source: https://docs.surge.app/api-reference/webhooks/events/message-failed

Example payload structure for the 'message.failed' webhook event, indicating when a message sent from a Surge number fails delivery.

```json
{
  "account_id": "acct_01japd271aeatb7txrzr2xj8sg",
  "data": {
    "id": "msg_01jjnn7s0zfx5tdcsxjfy93et2",
    "body": "Dude, I almost had you!",
    "attachments": [
      {
        "id": "att_01jjnn75vgepj8bnnttfw1st5s",
        "type": "image",
        "url": "https://toretto.family/skyline.jpg"
      }
    ],
    "conversation": {
      "id": "cnv_01jav8xy7fe4nsay3c9deqxge9",
      "phone_number": {
        "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
        "number": "+18015556789",
        "type": "local"
      },
      "contact": {
        "email": "dom@toretto.family",
        "id": "ctc_01ja88cboqffhswjx8zbak3ykk",
        "last_name": "Dominic",
        "first_name": "Toretto",
        "metadata": {
          "car": "1970 Dodge Charger R/T"
        },
        "phone_number": "+18015551234"
      }
    },
    "failed_at": "2024-10-21T23:29:42Z",
    "failure_reason": "carrier_error"
  },
  "type": "message.failed"
}
```

--------------------------------

### Surge API Reference

Source: https://docs.surge.app/api-reference/endpoint/verifications/create

Comprehensive API documentation for Surge.app, detailing endpoints for various functionalities. This includes methods for creating and updating accounts, sending blasts, managing contacts, sending messages, handling phone numbers, creating users and tokens, managing verifications, and setting up webhooks.

```APIDOC
API Endpoints:

Accounts:
  POST /accounts/create
    - Creates a new account.
  GET /accounts/get-account
    - Retrieves account details.
  PATCH /accounts/update
    - Updates an existing account.

Blasts:
  POST /blasts/send
    - Sends a blast message.

Contacts:
  POST /contacts/create
    - Creates a new contact.
  GET /contacts/get-contact
    - Retrieves a specific contact.
  PATCH /contacts/update
    - Updates an existing contact.

Messages:
  POST /messages/send
    - Sends a message.

Phone Numbers:
  POST /phone-numbers/create
    - Creates a new phone number.

Users:
  POST /users/create
    - Creates a new user.
  GET /users/get-user
    - Retrieves a specific user.

Tokens:
  POST /tokens/create-token
    - Creates a signed user token.

Verifications:
  POST /verifications
    - Creates a new Verification and sends the code to the given phone number.
    - Request Body:
      - phone_number (string, required): The phone number to be verified. In E.164 format.
    - Response Body (201 Created):
      - attempt_count (integer): The number of times the code has been attempted.
      - id (string): Unique identifier for the object.
      - phone_number (string): The phone number being verified. In E.164 format.
      - status (enum): The current status of the verification. Allowed values: pending, verified, exhausted, expired.
  POST /verifications/check
    - Checks the status of a verification.

Webhooks:
  Introduction: Overview of webhook functionality.
  Signature validation: Details on validating webhook signatures.
```

--------------------------------

### Accounts API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoints for managing accounts within the Surge platform. Includes creating new accounts and updating existing ones.

```APIDOC
POST /accounts/create
  Description: Creates a new account.
  Parameters:
    (Request Body) - Account creation details.
  Returns:
    Details of the newly created account.
```

```APIDOC
PATCH /accounts/update
  Description: Updates an existing account.
  Parameters:
    (Request Body) - Account update details.
  Returns:
    Details of the updated account.
```

--------------------------------

### Verifications API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoints for managing verification processes. Includes initiating and checking verification status.

```APIDOC
POST /verifications/create
  Description: Initiates a new verification process.
  Parameters:
    (Request Body) - Verification initiation details.
  Returns:
    Status of the verification initiation.
```

```APIDOC
POST /verifications/check
  Description: Checks the status of a verification.
  Parameters:
    (Request Body) - Verification check details.
  Returns:
    The current status of the verification.
```

--------------------------------

### Accounts API Endpoints

Source: https://docs.surge.app/index

Endpoints for managing accounts within the Surge platform. Includes creating new accounts and updating existing ones.

```APIDOC
POST /accounts/create
  Description: Creates a new account.
  Parameters:
    (Request Body) - Account creation details.
  Returns:
    Details of the newly created account.
```

```APIDOC
PATCH /accounts/update
  Description: Updates an existing account.
  Parameters:
    (Request Body) - Account update details.
  Returns:
    Details of the updated account.
```

--------------------------------

### Verifications API Endpoints

Source: https://docs.surge.app/index

Endpoints for managing verification processes. Includes initiating and checking verification status.

```APIDOC
POST /verifications/create
  Description: Initiates a new verification process.
  Parameters:
    (Request Body) - Verification initiation details.
  Returns:
    Status of the verification initiation.
```

```APIDOC
POST /verifications/check
  Description: Checks the status of a verification.
  Parameters:
    (Request Body) - Verification check details.
  Returns:
    The current status of the verification.
```

--------------------------------

### Webhooks Introduction and Signature Validation

Source: https://docs.surge.app/api-reference/endpoint/accounts/create

Provides an introduction to Surge webhooks and details on how to validate webhook signatures to ensure authenticity.

```APIDOC
Webhooks Introduction:
  (General overview of Surge webhooks, event types, and setup would be here)

---

Signature Validation:
  Description:
    Validates the signature of incoming webhook requests to ensure they originate from Surge and have not been tampered with.
  Process:
    1. Obtain the raw request body and the 'Surge-Signature' header.
    2. Use your secret signing key (provided by Surge) to compute the expected signature.
    3. Compare the computed signature with the received 'Surge-Signature' header.
  Parameters:
    - Raw Request Body: The complete, unparsed body of the incoming webhook request.
    - Surge-Signature Header: Contains the signature generated by Surge.
    - Signing Key: Your secret key provided by Surge for signature verification.
  Example (Conceptual):
    // Pseudocode for signature validation
    const crypto = require('crypto');
    const signingKey = process.env.SURGE_SIGNING_KEY;
    const signature = request.headers['surge-signature'];
    const payload = request.body;

    const hmac = crypto.createHmac('sha256', signingKey);
    hmac.update(payload);
    const computedSignature = hmac.digest('hex');

    if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computedSignature))) {
      // Signature is valid
    } else {
      // Signature is invalid
    }
```

--------------------------------

### Message Delivered Event Payload

Source: https://docs.surge.app/api-reference/webhooks/events/message-delivered

Example JSON payload for the 'message.delivered' webhook event. This event is triggered when a message sent from a Surge number is successfully delivered to the recipient's device.

```JSON
{
  "account_id": "acct_01japd271aeatb7txrzr2xj8sg",
  "data": {
    "id": "msg_01jjnn7s0zfx5tdcsxjfy93et2",
    "body": "Dude, I almost had you!",
    "attachments": [
      {
        "id": "att_01jjnn75vgepj8bnnttfw1st5s",
        "type": "image",
        "url": "https://toretto.family/skyline.jpg"
      }
    ],
    "delivered_at": "2024-10-21T23:29:42Z",
    "conversation": {
      "id": "cnv_01jav8xy7fe4nsay3c9deqxge9",
      "phone_number": {
        "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
        "number": "+18015556789",
        "type": "local"
      },
      "contact": {
        "email": "dom@toretto.family",
        "id": "ctc_01ja88cboqffhswjx8zbak3ykk",
        "last_name": "Dominic",
        "first_name": "Toretto",
        "metadata": {
          "car": "1970 Dodge Charger R/T"
        },
        "phone_number": "+18015551234"
      }
    }
  },
  "type": "message.delivered"
}
```

--------------------------------

### Create Verification in Python

Source: https://docs.surge.app/api-reference/endpoint/verifications/create

Demonstrates how to use the Surge Python client to initiate a verification process for a specified phone number. This involves authenticating with your Surge account and token, then calling the create method.

```Python
from surge import Surge

client = Surge(
    surge_account="YOUR_SURGE_ACCOUNT",
    token="YOUR_TOKEN",
)

client.verifications.create(
    phone_number="+18015551234",
)
```

--------------------------------

### Call Ended Webhook Event

Source: https://docs.surge.app/api-reference/webhooks/events/call-ended

Details the `call.ended` webhook event, which is triggered when a call between a Surge number and another phone number is completed. Includes example payload and common use cases.

```APIDOC
Event: call.ended

Description: Delivered whenever a call is completed between a Surge number and another phone number.

Common Use Cases:
  - Display calls in a log in your system.
  - Trigger follow-up actions.
  - Update customer analytics.

Payload Structure:
  account_id: string (Required) - The ID of the account that received the message.
  type: string (Required) - Always `call.ended` for this event.
  data: call (Object)
    id: string - The unique identifier for the call.
    contact: contact (Object)
      id: string - The unique identifier for the contact.
      email: string - The email address of the contact.
      first_name: string - The first name of the contact.
      last_name: string - The last name of the contact.
      phone_number: string - The contact’s phone number in E.164 format.
      metadata: object - Custom metadata associated with the contact.
    duration: integer - The duration of the call in seconds.
    initiated_at: string - ISO 8601 timestamp of when the call began.
    status: enum (busy, canceled, completed, failed, missed, no_answer) - The status of the call.
```

```json
{
  "account_id": "acct_01japd271aeatb7txrzr2xj8sg",
  "data": {
    "id": "call_01jjnn7s0zfx5tdcsxjfy93et2",
    "contact": {
      "id": "ctc_01ja88cboqffhswjx8zbak3ykk",
      "email": "dom@toretto.family",
      "first_name": "Dominic",
      "last_name": "Toretto",
      "metadata": {
        "car": "1970 Dodge Charger R/T"
      },
      "phone_number": "+18015551234"
    },
    "duration": 184,
    "initiated_at": "2025-03-31T21:01:37Z",
    "status": "completed"
  },
  "type": "call.ended"
}
```

--------------------------------

### Surge API Endpoints Overview

Source: https://docs.surge.app/api-reference/webhooks/introduction

Lists available API endpoints for managing various Surge functionalities including accounts, blasts, contacts, messages, phone numbers, users, tokens, and verifications.

```APIDOC
API Reference:

Accounts:
  POST /accounts/create
  PATCH /accounts/update

Blasts:
  POST /blasts/send

Contacts:
  POST /contacts/create
  GET /contacts/get-contact
  PATCH /contacts/update

Messages:
  POST /messages/send

Phone Numbers:
  POST /phone-numbers/create

Users:
  POST /users/create
  GET /users/get-user

Tokens:
  POST /tokens/create-token

Verifications:
  POST /verifications/create
  POST /verifications/check

Webhooks:
  Introduction
  Signature validation
```

--------------------------------

### Message Sent Event Payload

Source: https://docs.surge.app/api-reference/webhooks/events/message-sent

Example JSON payload received when a message is successfully sent from your Surge number to another phone number. This event is crucial for tracking message delivery and updating conversation analytics.

```json
{
  "account_id": "acct_01japd271aeatb7txrzr2xj8sg",
  "data": {
    "id": "msg_01jjnn7s0zfx5tdcsxjfy93et2",
    "body": "Dude, I almost had you!",
    "attachments": [
      {
        "id": "att_01jjnn75vgepj8bnnttfw1st5s",
        "type": "image",
        "url": "https://toretto.family/skyline.jpg"
      }
    ],
    "sent_at": "2024-10-21T23:29:41Z",
    "conversation": {
      "id": "cnv_01jav8xy7fe4nsay3c9deqxge9",
      "phone_number": {
        "id": "pn_01jsjwe4d9fx3tpymgtg958d9w",
        "number": "+18015556789",
        "type": "local"
      },
      "contact": {
        "email": "dom@toretto.family",
        "id": "ctc_01ja88cboqffhswjx8zbak3ykk",
        "last_name": "Dominic",
        "first_name": "Toretto",
        "metadata": {
          "car": "1970 Dodge Charger R/T"
        },
        "phone_number": "+18015551234"
      }
    },
    "type": "message.sent"
  }
}
```

--------------------------------

### Handle Token Expiration in JavaScript

Source: https://docs.surge.app/ui/home/authentication

This JavaScript snippet demonstrates how to listen for 'token_expiring' messages from an iframe. Upon receiving such a message, it calls a hypothetical `refreshSurgeToken` function to get a new token and then posts an 'update_token' message back to the iframe.

```javascript
const surgeInbox = document.querySelector('iframe#surge-inbox');

window.addEventListener('message', async ({ data, origin }) => {
  if (origin == 'https://embed.surge.app') {
    const { type } = data;

    if (type == 'token_expiring') {
      const { token } = await refreshSurgeToken();
      const message = { type: 'update_token', data: { token }};
      surgeInbox.contentWindow.postMessage(message, origin);
    }
  }
});
```

--------------------------------

### Contacts API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoints for managing contacts. Includes creating, retrieving, and updating contact information.

```APIDOC
POST /contacts/create
  Description: Creates a new contact.
  Parameters:
    (Request Body) - Contact creation details.
  Returns:
    Details of the newly created contact.
```

```APIDOC
GET /contacts/get-contact
  Description: Retrieves a specific contact.
  Parameters:
    contactId: The unique identifier for the contact.
  Returns:
    Details of the requested contact.
```

```APIDOC
PATCH /contacts/update
  Description: Updates an existing contact.
  Parameters:
    (Request Body) - Contact update details.
  Returns:
    Details of the updated contact.
```

--------------------------------

### Tokens API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoint for creating signed user tokens, used for authentication and authorization.

```APIDOC
POST /tokens/create-token
  Description: Creates a signed user token.
  Parameters:
    (Request Body) - Token creation details.
  Returns:
    The signed user token.
```

--------------------------------

### Tokens API Endpoints

Source: https://docs.surge.app/index

Endpoint for creating signed user tokens, used for authentication and authorization.

```APIDOC
POST /tokens/create-token
  Description: Creates a signed user token.
  Parameters:
    (Request Body) - Token creation details.
  Returns:
    The signed user token.
```

--------------------------------

### Surge API - Blast Management

Source: https://docs.surge.app/api-reference/endpoint/accounts/update

This section details the API endpoint for sending blasts through the Surge platform. It outlines the necessary parameters for initiating a blast.

```APIDOC
API Reference:

Blasts:
  + POST Send a blast (/api-reference/endpoint/blasts/send)

Send a blast:
  Method: POST
  URL: https://api.surge.app/blasts
  Description: Sends a blast to specified recipients.
  Parameters:
    (Details for Send a blast endpoint would be listed here if available in the input text)

  Related Endpoints:
    - POST Create an account (/api-reference/endpoint/accounts/create)
    - PATCH Update an account (/api-reference/endpoint/accounts/update)
```

--------------------------------

### Contacts API Endpoints

Source: https://docs.surge.app/index

Endpoints for managing contacts. Includes creating, retrieving, and updating contact information.

```APIDOC
POST /contacts/create
  Description: Creates a new contact.
  Parameters:
    (Request Body) - Contact creation details.
  Returns:
    Details of the newly created contact.
```

```APIDOC
GET /contacts/get-contact
  Description: Retrieves a specific contact.
  Parameters:
    contactId: The unique identifier for the contact.
  Returns:
    Details of the requested contact.
```

```APIDOC
PATCH /contacts/update
  Description: Updates an existing contact.
  Parameters:
    (Request Body) - Contact update details.
  Returns:
    Details of the updated contact.
```

--------------------------------

### Update a Contact (Python SDK)

Source: https://docs.surge.app/api-reference/endpoint/contacts/update

Demonstrates how to update an existing contact using the Surge Python SDK. It shows client initialization and the specific method call for updating contact details.

```python
from surge import Surge

client = Surge(
  surge_account="YOUR_SURGE_ACCOUNT",
  token="YOUR_TOKEN",
)
client.contacts.update(
  id="ctc_01j9dy8mdzfn3r0e8x1tbdrdrf",
)
```

--------------------------------

### Surge API Endpoints Overview

Source: https://docs.surge.app/api-reference/endpoint/phone-numbers/create

Lists available API endpoints for various functionalities within the Surge platform, including account management, contact operations, message sending, phone number provisioning, user management, token generation, verification processes, and webhook handling.

```APIDOC
API Reference:

Accounts:
  POST /accounts/:account_id/create
  PATCH /accounts/:account_id/update

Blasts:
  POST /blasts/send

Contacts:
  POST /contacts/create
  GET /contacts/get-contact
  PATCH /contacts/update

Messages:
  POST /messages/send

Phone Numbers:
  POST /accounts/:account_id/phone_numbers

Users:
  POST /users/create
  GET /users/get-user

Tokens:
  POST /tokens/create-token

Verifications:
  POST /verifications/create
  POST /verifications/check

Webhooks:
  Introduction
  Signature validation
```

--------------------------------

### Create and Check Verification

Source: https://docs.surge.app/api-reference/endpoint/accounts/create

Handles the creation and checking of verification processes, likely for phone numbers or accounts. Includes endpoints for initiating and verifying.

```APIDOC
POST /verifications/create

Description:
  Initiates a verification process, e.g., sending a code to a phone number.

Request:
  Headers:
    Authorization: Bearer <token> (string, Required)
    Content-Type: application/json
  Body:
    (Details for initiating verification, e.g., phone number, channel, would be specified here)

Response:
  (Details about the verification initiation, e.g., a verification ID, would be specified here)

---

POST /verifications/check

Description:
  Checks the validity of a submitted verification code against an ongoing verification.

Request:
  Headers:
    Authorization: Bearer <token> (string, Required)
    Content-Type: application/json
  Body:
    verificationId: The ID of the verification process (string, Required)
    code: The code submitted by the user (string, Required)

Response:
  Body:
    isValid: Boolean indicating if the code is valid (boolean)
    (Other relevant status information might be included)
```

--------------------------------

### Create a User

Source: https://docs.surge.app/api-reference/endpoint/accounts/create

Creates a new user within the platform. Requires user details such as name and email.

```APIDOC
POST /users

Request:
  Headers:
    Authorization: Bearer <token> (string, Required)
    Content-Type: application/json
  Body:
    (Details for user creation, e.g., name, email, password, would be specified here)

Response:
  (Details of the created user, including an ID, would be specified here)

Related:
  - Retrieve a user: GET /users/get-user
```

--------------------------------

### Create a User

Source: https://docs.surge.app/api-reference/endpoint/users/create

Creates a new User object within a specified account. This endpoint requires authentication and provides detailed parameters for user information.

```APIDOC
POST /accounts/:account_id/users

Creates a new User object.

### Path parameters
- account_id: string (Required) - The account for which the user should be created.

### Headers
- Authorization: string (Required) - Bearer authentication of the form Bearer <token>, where token is your auth token.

### Request
User params:
- first_name: string (Required) - The user's first name.
- last_name: string (Optional) - The user's last name.
- metadata: object (Optional) - Set of key-value pairs that will be stored with the user.
- photo_url: string (Optional, format: "url") - URL of a photo to be used as the user's avatar.

### Response
User:
- first_name: string or null - The user's first name.
- id: string or null - Unique identifier for the object.
- last_name: string or null - The user's last name.
- metadata: object or null - Set of key-value pairs that will be stored with the user.
- photo_url: string or null (format: "url") - URL of a photo to be used as the user's avatar.

Example Response:
{
  "first_name": "Brian",
  "id": "usr_01j9dwavghe1ttppewekjjkfrx",
  "last_name": "O'Conner",
  "metadata": {
    "email": "boconner@toretti.family",
    "user_id": 1234
  },
  "photo_url": "https://toretti.family/people/brian.jpg"
}
```

--------------------------------

### API: Create Contact

Source: https://docs.surge.app/api-reference/endpoint/contacts/create

Reference for the POST /accounts/:account_id/contacts endpoint used to create a new contact. Includes details on path parameters, required headers, request body schema, and the structure of the response.

```APIDOC
POST /accounts/:account_id/contacts

Creates a new Contact object.

Path Parameters:
  account_id: string (Required) - The account for which the contact should be created.

Headers:
  Authorization: string (Required) - Bearer authentication of the form Bearer <token>, where token is your auth token.

Request Body:
  Contact params:
    phone_number: string (Required, format: "phone_number") - The contact's phone number in E.164 format.
    email: string (Optional, format: "email") - The contact's email address.
    first_name: string (Optional) - The contact's first name.
    last_name: string (Optional) - The contact's last name.
    metadata: map from strings to any (Optional) - Additional metadata about the contact.

Response Body:
  Contact:
    email: string or null (format: "email") - The contact's email address.
    first_name: string or null - The contact's first name.
    id: string or null - Unique identifier for the object.
    last_name: string or null - The contact's last name.
    metadata: map from strings to any or null - Additional metadata about the contact.
    phone_number: string or null (format: "phone_number") - The contact's phone number in E.164 format.

Example Response (201 Created):
{
  "email": "dom@toretto.family",
  "first_name": "Dominic",
  "id": "ctc_01j9dy8mdzfn3r0e8x1tbdrdrf",
  "last_name": "Toretto",
  "metadata": {
    "car": "1970 Dodge Charger R/T"
  },
  "phone_number": "+18015551234"
}
```

--------------------------------

### Create an Account

Source: https://docs.surge.app/api-reference/endpoint/accounts/create

Creates a new Account within the calling Platform. Requires account name and optionally accepts a time zone.

```APIDOC
POST /accounts

Request:
  Headers:
    Authorization: Bearer <token> (string, Required)
    Content-Type: application/json
  Body:
    name: The name of the account (string, Required)
    time_zone: The time zone for the account (string or null, Optional)

Response (201 Created):
  Body:
    id: The account ID (string)
    name: The name of the account (string)
    time_zone: The time zone for the account (string or null)

Example cURL:
curl -X POST https://api.surge.app/accounts \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ \
  "name": "D·T Precision Auto Shop", \
  "time_zone": "America/Los_Angeles" \
}'

Related:
  - Update an account: PATCH /accounts
```

--------------------------------

### Surge API Endpoints Overview

Source: https://docs.surge.app/api-reference/webhooks/events/conversation-created

This section provides a high-level overview of available API endpoints for managing various resources within the Surge platform, including accounts, contacts, messages, and users.

```APIDOC
Accounts:
  POST /api-reference/endpoint/accounts/create - Create an account
  PATCH /api-reference/endpoint/accounts/update - Update an account

Blasts:
  POST /api-reference/endpoint/blasts/send - Send a blast

Contacts:
  POST /api-reference/endpoint/contacts/create - Create a contact
  GET /api-reference/endpoint/contacts/get-contact - Retrieve a contact
  PATCH /api-reference/endpoint/contacts/update - Update a contact

Messages:
  POST /api-reference/endpoint/messages/send - Send a message

Phone Numbers:
  POST /api-reference/endpoint/phone-numbers/create - Create a phone number

Users:
  POST /api-reference/endpoint/users/create - Create a user
  GET /api-reference/endpoint/users/get-user - Retrieve a user

Tokens:
  POST /api-reference/endpoint/tokens/create-token - Create a signed user token

Verifications:
  POST /api-reference/endpoint/verifications/create - Create a verification
  POST /api-reference/endpoint/verifications/check - Check a verification
```

--------------------------------

### Create a Phone Number

Source: https://docs.surge.app/api-reference/endpoint/accounts/create

Creates a new phone number resource. Requires details for provisioning the phone number.

```APIDOC
POST /phone-numbers

Request:
  Headers:
    Authorization: Bearer <token> (string, Required)
    Content-Type: application/json
  Body:
    (Details for phone number creation, e.g., country code, capabilities, would be specified here)

Response:
  (Details of the created phone number, including its ID and number, would be specified here)
```

--------------------------------

### Blasts API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoint for sending blasts through the Surge platform. Allows for mass communication.

```APIDOC
POST /blasts/send
  Description: Sends a blast message.
  Parameters:
    (Request Body) - Blast sending details.
  Returns:
    Status of the blast sending operation.
```

--------------------------------

### Retrieve a User

Source: https://docs.surge.app/api-reference/endpoint/users/get-user

Details on how to retrieve a specific user's information using the Surge API. Includes the HTTP method, endpoint, path parameters, required headers, and a sample response structure.

```APIDOC
GET /users/:id

Retrieves a User object.

### Path parameters
- id: string (Required) - Unique identifier for the user.

### Headers
- Authorization: string (Required) - Bearer authentication of the form Bearer <token>, where token is your auth token.

### Response (200 OK)
User object:
- first_name: string or null - The user's first name.
- id: string or null - Unique identifier for the object.
- last_name: string or null - The user's last name.
- metadata: object or null - Set of key-value pairs that will be stored with the user.
- photo_url: string or null (format: "url") - URL of a photo to be used as the user's avatar.
```

--------------------------------

### Surge API - User Management

Source: https://docs.surge.app/api-reference/endpoint/accounts/update

This section details the API endpoints for managing users within the Surge platform. It covers creating and retrieving user information.

```APIDOC
API Reference:

Users:
  + POST Create a user (/api-reference/endpoint/users/create)
  + GET Retrieve a user (/api-reference/endpoint/users/get-user)

(Details for Create and Retrieve user endpoints would be listed here if available in the input text)
```

--------------------------------

### Create a Contact

Source: https://docs.surge.app/api-reference/endpoint/accounts/create

Creates a new contact. Requires contact details such as name and phone number.

```APIDOC
POST /contacts

Request:
  Headers:
    Authorization: Bearer <token> (string, Required)
    Content-Type: application/json
  Body:
    (Details for contact creation, e.g., name, phone, email, would be specified here)

Response:
  (Details for the created contact, including an ID, would be specified here)

Related:
  - Retrieve a contact: GET /contacts/get-contact
  - Update a contact: PATCH /contacts
```

--------------------------------

### Surge API Endpoints

Source: https://docs.surge.app/api-reference/webhooks/events/call-ended

Overview of available API endpoints for various functionalities within Surge.app, including account management, contact operations, message sending, and user management.

```APIDOC
Accounts:
  POST /accounts/create
    - Creates a new account.
  PATCH /accounts/update
    - Updates an existing account.

Blasts:
  POST /blasts/send
    - Sends a blast message.

Contacts:
  POST /contacts/create
    - Creates a new contact.
  GET /contacts/get-contact
    - Retrieves details of a specific contact.
  PATCH /contacts/update
    - Updates an existing contact.

Messages:
  POST /messages/send
    - Sends a message.

Phone Numbers:
  POST /phone-numbers/create
    - Creates a new phone number.

Users:
  POST /users/create
    - Creates a new user.
  GET /users/get-user
    - Retrieves details of a specific user.

Tokens:
  POST /tokens/create-token
    - Creates a signed user token.

Verifications:
  POST /verifications/create
    - Creates a new verification.
  POST /verifications/check
    - Checks the status of a verification.

Webhooks:
  Introduction: Overview of webhook functionality.
  Signature validation: Details on validating webhook signatures.
  Events: Information on various webhook events.
```

--------------------------------

### Blasts API Endpoints

Source: https://docs.surge.app/index

Endpoint for sending blasts through the Surge platform. Allows for mass communication.

```APIDOC
POST /blasts/send
  Description: Sends a blast message.
  Parameters:
    (Request Body) - Blast sending details.
  Returns:
    Status of the blast sending operation.
```

--------------------------------

### Surge API - Verification Management

Source: https://docs.surge.app/api-reference/endpoint/accounts/update

This section details the API endpoints for managing verifications within the Surge platform. It covers creating and checking verification statuses.

```APIDOC
API Reference:

Verifications:
  + POST Create a verification (/api-reference/endpoint/verifications/create)
  + POST Check a verification (/api-reference/endpoint/verifications/check)

(Details for Create and Check verification endpoints would be listed here if available in the input text)
```

--------------------------------

### Phone Numbers API Endpoints

Source: https://docs.surge.app/api-reference/home/introduction

Endpoint for managing phone numbers. Allows for the creation of new phone numbers.

```APIDOC
POST /phone-numbers/create
  Description: Creates a new phone number.
  Parameters:
    (Request Body) - Phone number creation details.
  Returns:
    Details of the newly created phone number.
```
Tokens:
Raw