SureContact API Documentation

Introduction

SureContact Public API for external integrations.

Base URL: https://api.surecontact.com

This documentation provides all the information you need to work with the SureContact Public API.

Authentication

All Public API endpoints require an API key. Include it in the request header:

X-API-Key: surecontact_your_api_key_here

Or using the Authorization header with Bearer prefix:

Authorization: Bearer surecontact_your_api_key_here

Getting an API Key

Log in to SureContact
Navigate to Profile on Top Bar > API Keys
Click Create API Key
Select the required abilities (read, write, delete)
Copy the key immediately (it won't be shown again)

Rate Limiting

API requests are rate-limited based on your organization's plan. Rate limit information is included in response headers:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Remaining requests in the window
X-RateLimit-Reset - Unix timestamp when the limit resets

Authenticating requests

To authenticate requests, include a X-API-Key header with the value "{YOUR_API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can create API keys from the Profile > API Keys section in the dashboard.

Contact Activities

APIs for viewing and creating contact activities. Activities represent events and interactions associated with a contact, forming an audit trail of all engagements.

Activity types include: email_sent, email_opened, email_clicked, form_submitted, note_added, note_updated, note_deleted, tag_added, tag_removed, contact_created, contact_updated, list_added, list_removed, custom_field_added, custom_field_updated, custom_field_deleted, purchase_completed, purchase_cancelled, purchase_refunded.

Available via both authenticated API (Sanctum) and Public API (API Key).

List Activities

GET

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/activities

requires authentication

Get paginated activities for a specific contact. Activities are returned in reverse chronological order (newest first).

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

contact

string

required

The UUID of the contact.

Example:

550e8400-e29b-41d4-a716-446655440000

Query Parameters

type

string

Filter by activity type.

Example:

email_sent

from

string

Filter activities from this date (ISO 8601).

Example:

2025-01-01T00:00:00+00:00

string

Filter activities until this date (ISO 8601).

Example:

2025-01-31T23:59:59+00:00

days

integer

Filter to activities from the last N days.

Example:

per_page

integer

Number of items per page. Default: 15.

Example:

Auth

Headers

URL Parameters

Query Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/activities?type=email_sent&from=2025-01-01T00%3A00%3A00%2B00%3A00&to=2025-01-31T23%3A59%3A59%2B00%3A00&days=30&per_page=20" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "uuid": 123,
            "type": "email_sent",
            "type_label": "Email Sent",
            "icon": "mail",
            "color": "blue",
            "description": "Campaign email sent to contact",
            "metadata": {
                "campaign_id": "campaign-uuid",
                "subject": "Welcome to our newsletter"
            },
            "contact": {
                "uuid": "contact-uuid",
                "email": "[email protected]",
                "full_name": "John Doe"
            },
            "created_by": {
                "uuid": "user-uuid",
                "name": "System",
                "email": "[email protected]"
            },
            "created_at": "2025-01-15T10:30:00+00:00"
        }
    ],
    "links": {},
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 50
    }
}

Get Activity

GET

https://api.surecontact.com

/api/v1/public/activities/{activity_uuid}

requires authentication

Get details of a specific activity.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

activity_uuid

string

required

Example:

3970df41-25c8-4100-8a4f-4c2eb7e3346e

activity

string

required

The UUID of the activity.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/activities/3970df41-25c8-4100-8a4f-4c2eb7e3346e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "type": "form_submitted",
        "type_label": "Form Submitted",
        "icon": "document-text",
        "color": "indigo",
        "description": "Contact submitted the newsletter signup form",
        "metadata": {
            "form_name": "Newsletter Signup",
            "page_url": "https://example.com/signup"
        },
        "contact": {
            "uuid": "contact-uuid",
            "email": "[email protected]",
            "full_name": "John Doe"
        },
        "created_by": {
            "uuid": "user-uuid",
            "name": "API Integration",
            "email": "[email protected]"
        },
        "created_at": "2025-01-15T10:30:00+00:00"
    }
}

Create Activity

POST

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/activities

requires authentication

Create a new activity for a contact. This is useful for logging external events or custom integrations. The activity will be attributed to the authenticated user (or API key owner).

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

contact

string

required

The UUID of the contact.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

type

string

required

The activity type. Allowed values: email_sent, email_opened, email_clicked, form_submitted, note_added, note_updated, note_deleted, tag_added, tag_removed, contact_created, contact_updated, list_added, list_removed, custom_field_added, custom_field_updated, custom_field_deleted, purchase_completed, purchase_cancelled, purchase_refunded.

Example:

form_submitted

description

string

required

A description of the activity. Max 1,000 characters.

Example:

Customer submitted the contact form on the pricing page.

metadata

object

Optional metadata for the activity. Can contain any key-value pairs.

Example:

{"form_name":"Contact Form","page_url":"https:\/\/example.com\/pricing"}

Auth

Headers

URL Parameters

Body

{ "type": "form_submitted", "description": "Customer submitted the contact form on the pricing page.", "metadata": { "form_name": "Contact Form", "page_url": "https:\/\/example.com\/pricing" } }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/activities" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"type\": \"form_submitted\",
    \"description\": \"Customer submitted the contact form on the pricing page.\",
    \"metadata\": {
        \"form_name\": \"Contact Form\",
        \"page_url\": \"https:\\/\\/example.com\\/pricing\"
    }
}"

Example response:

{
    "data": {
        "uuid": 456,
        "type": "form_submitted",
        "type_label": "Form Submitted",
        "icon": "document-text",
        "color": "indigo",
        "description": "Customer submitted the contact form on the pricing page.",
        "metadata": {
            "form_name": "Contact Form",
            "page_url": "https://example.com/pricing"
        },
        "contact": {
            "uuid": "contact-uuid",
            "email": "[email protected]",
            "full_name": "John Doe"
        },
        "created_by": {
            "uuid": "user-uuid",
            "name": "API Integration",
            "email": "[email protected]"
        },
        "created_at": "2025-01-15T10:30:00+00:00"
    }
}

Contact Management

APIs for managing contacts within a workspace. Contacts are the core entity representing individuals you interact with.

Get paginated contacts

GET

https://api.surecontact.com

/api/v1/public/contacts

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Auth

Headers

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Find Contact by Email

GET

https://api.surecontact.com

/api/v1/public/contacts/email/{email}

requires authentication

Look up a contact by their email address. Returns the contact if found, or a 404 response if no contact exists with the given email.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

string

required

The email address to search for.

Example:

[email protected]

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts/email/[email protected]" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "success": true,
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "status": "subscribed",
        "created_at": "2025-01-10T10:00:00+00:00",
        "updated_at": "2025-01-10T10:00:00+00:00"
    }
}

Show a specific contact

GET

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Find or Create Contact

POST

https://api.surecontact.com

/api/v1/public/contacts

requires authentication

Find an existing contact by email or create a new one if not found. This is an idempotent operation - calling multiple times with the same email will return the same contact without modifications.

Behavior:

If contact with email exists → Return existing contact (no updates)
If contact doesn't exist → Create new contact with provided data

Use this endpoint when you want to ensure a contact exists without overwriting any existing data.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

primary_fields

object

required

The primary contact information.

string

required

The contact's email address. Used to find existing contact or create new one.

Example:

[email protected]

first_name

string

The contact's first name.

Example:

John

last_name

string

The contact's last name.

Example:

Doe

phone

string

The contact's phone number.

Example:

+1234567890

company

string

The contact's company name.

Example:

Acme Inc

job_title

string

The contact's job title.

Example:

Marketing Manager

birthdate

string

The contact's date of birth.

Example:

1990-01-15

gender

string

The contact's gender (male, female, other, prefer_not_to_say).

Example:

male

anniversary

string

A significant date for the contact (e.g., wedding anniversary). Must be a valid date.

Example:

2015-06-20

prefix

string

Name prefix (Mr, Ms, Mrs, Dr, etc.). Must not be greater than 20 characters.

Example:

suffix

string

Name suffix (Jr, Sr, III, etc.). Must not be greater than 20 characters.

Example:

source

string

How the contact was acquired (manual, import, api, form, integration).

Example:

api

metadata

object

Additional metadata as key-value pairs.

Example:

{"utm_source":"google"}

custom_fields

object

Custom field values. Keys are field names, values are field values.

Example:

{"industry":"Technology"}

Auth

Headers

Body

{ "primary_fields": { "email": "[email protected]", "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "company": "Acme Inc", "job_title": "Marketing Manager", "birthdate": "1990-01-15", "gender": "male", "anniversary": "2015-06-20", "prefix": "Dr", "suffix": "Jr", "source": "api" }, "metadata": { "utm_source": "google" }, "custom_fields": { "industry": "Technology" } }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"primary_fields\": {
        \"email\": \"[email protected]\",
        \"first_name\": \"John\",
        \"last_name\": \"Doe\",
        \"phone\": \"+1234567890\",
        \"company\": \"Acme Inc\",
        \"job_title\": \"Marketing Manager\",
        \"birthdate\": \"1990-01-15\",
        \"gender\": \"male\",
        \"anniversary\": \"2015-06-20\",
        \"prefix\": \"Dr\",
        \"suffix\": \"Jr\",
        \"source\": \"api\"
    },
    \"metadata\": {
        \"utm_source\": \"google\"
    },
    \"custom_fields\": {
        \"industry\": \"Technology\"
    }
}"

Example response:

{
    "success": true,
    "is_created": false,
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "status": "subscribed",
        "created_at": "2025-01-10T10:00:00+00:00",
        "updated_at": "2025-01-10T10:00:00+00:00"
    }
}

Upsert Contact

POST

https://api.surecontact.com

/api/v1/public/contacts/upsert

requires authentication

Create a new contact or update an existing one based on email address. This is an idempotent operation ideal for syncing contact data from external systems.

Behavior:

If contact with email exists → Update with provided data, return with is_created: false
If contact doesn't exist → Create new contact, return with is_created: true

Use this endpoint when you want to keep contact data synchronized with an external system.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

primary_fields

object

required

The primary contact information.

string

required

The contact's email address. Used to find existing contact or create new one.

Example:

[email protected]

first_name

string

The contact's first name.

Example:

John

last_name

string

The contact's last name.

Example:

Doe

phone

string

The contact's phone number.

Example:

+1234567890

company

string

The contact's company name.

Example:

Acme Inc

job_title

string

The contact's job title.

Example:

Marketing Manager

birthdate

string

The contact's date of birth.

Example:

1990-01-15

gender

string

The contact's gender (male, female, other, prefer_not_to_say).

Example:

male

anniversary

string

A significant date for the contact (e.g., wedding anniversary). Must be a valid date.

Example:

2015-06-20

prefix

string

Name prefix (Mr, Ms, Mrs, Dr, etc.). Must not be greater than 20 characters.

Example:

suffix

string

Name suffix (Jr, Sr, III, etc.). Must not be greater than 20 characters.

Example:

source

string

How the contact was acquired (manual, import, api, form, integration).

Example:

api

metadata

object

Additional metadata as key-value pairs.

Example:

{"utm_source":"google"}

custom_fields

object

Custom field values. Keys are field names, values are field values.

Example:

{"industry":"Technology"}

Auth

Headers

Body

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/upsert" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"primary_fields\": {
        \"email\": \"[email protected]\",
        \"first_name\": \"John\",
        \"last_name\": \"Doe\",
        \"phone\": \"+1234567890\",
        \"company\": \"Acme Inc\",
        \"job_title\": \"Marketing Manager\",
        \"birthdate\": \"1990-01-15\",
        \"gender\": \"male\",
        \"anniversary\": \"2015-06-20\",
        \"prefix\": \"Dr\",
        \"suffix\": \"Jr\",
        \"source\": \"api\"
    },
    \"metadata\": {
        \"utm_source\": \"google\"
    },
    \"custom_fields\": {
        \"industry\": \"Technology\"
    }
}"

Example response:

{
    "success": true,
    "is_created": false,
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "status": "subscribed",
        "created_at": "2025-01-10T10:00:00+00:00",
        "updated_at": "2025-01-15T10:30:00+00:00"
    }
}

Update a contact

PUT

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Body Parameters

primary_fields

object

The primary contact information to update.

string

The contact's email address. Must be unique within the workspace. Must be a valid email address.

Example:

[email protected]

first_name

string

The contact's first name. Must not be greater than 255 characters.

Example:

John

last_name

string

The contact's last name. Must not be greater than 255 characters.

Example:

Doe

phone

string

The contact's phone number. Must not be greater than 50 characters.

Example:

+1234567890

company

string

The contact's company name. Must not be greater than 255 characters.

Example:

Acme Inc

job_title

string

The contact's job title. Must not be greater than 255 characters.

Example:

Marketing Manager

birthdate

string

The contact's date of birth. Must be a valid date. Must be a date before today.

Example:

1990-01-15

gender

string

The contact's gender. Values: male, female, other, prefer_not_to_say.

Must be one of:

male
female
other
prefer_not_to_say

Example:

male

anniversary

string

A significant date for the contact (e.g., wedding anniversary). Must be a valid date.

Example:

2015-06-20

prefix

string

Name prefix (Mr, Ms, Mrs, Dr, etc.). Must not be greater than 20 characters.

Example:

suffix

string

Name suffix (Jr, Sr, III, etc.). Must not be greater than 20 characters.

Example:

source

string

How the contact was acquired. Values: manual, import, api, form, integration.

Must be one of:

wordpress
api
manual
import
form
webhook

Example:

api

metadata

object

Additional metadata as key-value pairs.

Example:

{"utm_source":"google","campaign":"spring_sale"}

custom_fields

object

Custom field values. Keys are custom field names, values are the field values.

Example:

{"industry":"Technology","company_size":"50-100"}

Auth

Headers

URL Parameters

Body

{ "primary_fields": { "email": "[email protected]", "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "company": "Acme Inc", "job_title": "Marketing Manager", "birthdate": "1990-01-15", "gender": "male", "anniversary": "2015-06-20", "prefix": "Dr", "suffix": "Jr", "source": "api" }, "metadata": { "utm_source": "google", "campaign": "spring_sale" }, "custom_fields": { "industry": "Technology", "company_size": "50-100" } }

Received response

Example request:

curl --request PUT \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"primary_fields\": {
        \"email\": \"[email protected]\",
        \"first_name\": \"John\",
        \"last_name\": \"Doe\",
        \"phone\": \"+1234567890\",
        \"company\": \"Acme Inc\",
        \"job_title\": \"Marketing Manager\",
        \"birthdate\": \"1990-01-15\",
        \"gender\": \"male\",
        \"anniversary\": \"2015-06-20\",
        \"prefix\": \"Dr\",
        \"suffix\": \"Jr\",
        \"source\": \"api\"
    },
    \"metadata\": {
        \"utm_source\": \"google\",
        \"campaign\": \"spring_sale\"
    },
    \"custom_fields\": {
        \"industry\": \"Technology\",
        \"company_size\": \"50-100\"
    }
}"

Update a contact's status

PATCH

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/status

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Body Parameters

status

string

required

The new status for the contact. Values: active, unsubscribed, bounced, invalid.

Must be one of:

active
unsubscribed
bounced
invalid

Example:

active

Auth

Headers

URL Parameters

Body

{ "status": "active" }

Received response

Example request:

curl --request PATCH \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/status" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"status\": \"active\"
}"

Attach tags to a contact

POST

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/tags/attach

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Body Parameters

tag_uuids

string[]

A valid tag UUID that exists in the workspace. Must be a valid UUID. The uuid of an existing record in the tags table.

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Auth

Headers

URL Parameters

Body

{ "tag_uuids": [ "550e8400-e29b-41d4-a716-446655440000" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/tags/attach" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"tag_uuids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}"

Detach tags from a contact

POST

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/tags/detach

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Body Parameters

tag_uuids

string[]

A valid tag UUID that exists in the workspace. Must be a valid UUID. The uuid of an existing record in the tags table.

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Auth

Headers

URL Parameters

Body

{ "tag_uuids": [ "550e8400-e29b-41d4-a716-446655440000" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/tags/detach" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"tag_uuids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}"

Attach lists to a contact

POST

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/lists/attach

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Body Parameters

list_uuids

string[]

A valid list UUID that exists in the workspace. Must be a valid UUID. The uuid of an existing record in the lists table.

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Auth

Headers

URL Parameters

Body

{ "list_uuids": [ "550e8400-e29b-41d4-a716-446655440000" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/lists/attach" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"list_uuids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}"

Detach lists from a contact

POST

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/lists/detach

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Body Parameters

list_uuids

string[]

A valid list UUID that exists in the workspace. Must be a valid UUID. The uuid of an existing record in the lists table.

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Auth

Headers

URL Parameters

Body

{ "list_uuids": [ "550e8400-e29b-41d4-a716-446655440000" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/lists/detach" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"list_uuids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}"

Delete a contact

DELETE

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

Auth

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Contact Notes

APIs for managing notes attached to contacts. Notes allow you to store free-form text information about a contact.

Available via both authenticated API (Sanctum) and Public API (API Key).

List Notes

GET

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/notes

requires authentication

Get paginated notes for a specific contact. Notes are returned in reverse chronological order (newest first).

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

contact

string

required

The UUID of the contact.

Example:

550e8400-e29b-41d4-a716-446655440000

Query Parameters

per_page

integer

Number of items per page. Default: 15.

Example:

page

integer

Page number.

Example:

Auth

Headers

URL Parameters

Query Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/notes?per_page=20&page=1" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "uuid": "note-uuid-here",
            "content": "Called customer to discuss renewal options.",
            "created_by": {
                "uuid": "user-uuid",
                "name": "John Doe",
                "email": "[email protected]"
            },
            "updated_by": null,
            "created_at": "2025-01-15T10:30:00+00:00",
            "updated_at": "2025-01-15T10:30:00+00:00"
        }
    ],
    "links": {},
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 5
    }
}

Get Note

GET

https://api.surecontact.com

/api/v1/public/notes/{note_uuid}

requires authentication

Get details of a specific note.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

note_uuid

string

required

Example:

77ce6a1f-5faa-4c6f-86ad-18a0963dc58e

note

string

required

The UUID of the note.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/notes/77ce6a1f-5faa-4c6f-86ad-18a0963dc58e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "uuid": "note-uuid-here",
        "content": "Customer requested a callback next week.",
        "created_by": {
            "uuid": "user-uuid",
            "name": "John Doe",
            "email": "[email protected]"
        },
        "updated_by": {
            "uuid": "user-uuid-2",
            "name": "Jane Smith",
            "email": "[email protected]"
        },
        "created_at": "2025-01-15T10:30:00+00:00",
        "updated_at": "2025-01-16T14:00:00+00:00"
    }
}

Create Note

POST

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/notes

requires authentication

Create a new note for a contact. The note will be attributed to the authenticated user (or API key owner for public API).

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

contact

string

required

The UUID of the contact.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

title

string

Optional title for the note. Max 255 characters. Must not be greater than 255 characters.

Example:

Renewal Discussion

content

string

required

The note content. Max 10,000 characters.

Example:

Customer requested a callback next week to discuss enterprise pricing.

Auth

Headers

URL Parameters

Body

{ "title": "Renewal Discussion", "content": "Customer requested a callback next week to discuss enterprise pricing." }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/notes" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"title\": \"Renewal Discussion\",
    \"content\": \"Customer requested a callback next week to discuss enterprise pricing.\"
}"

Example response:

{
    "data": {
        "uuid": "note-uuid-here",
        "content": "Customer requested a callback next week to discuss enterprise pricing.",
        "created_by": {
            "uuid": "user-uuid",
            "name": "John Doe",
            "email": "[email protected]"
        },
        "updated_by": null,
        "created_at": "2025-01-15T10:30:00+00:00",
        "updated_at": "2025-01-15T10:30:00+00:00"
    }
}

Update Note

PUT

https://api.surecontact.com

/api/v1/public/notes/{note_uuid}

requires authentication

Update an existing note. Only the note creator or workspace managers can update notes.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

note_uuid

string

required

Example:

77ce6a1f-5faa-4c6f-86ad-18a0963dc58e

note

string

required

The UUID of the note.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

title

string

Optional title for the note. Max 255 characters. Must not be greater than 255 characters.

Example:

Follow-up Call Scheduled

content

string

required

The updated note content. Max 10,000 characters.

Example:

Updated: Customer confirmed callback for Monday at 2pm.

Auth

Headers

URL Parameters

Body

{ "title": "Follow-up Call Scheduled", "content": "Updated: Customer confirmed callback for Monday at 2pm." }

Received response

Example request:

curl --request PUT \
    "https://api.surecontact.com/api/v1/public/notes/77ce6a1f-5faa-4c6f-86ad-18a0963dc58e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"title\": \"Follow-up Call Scheduled\",
    \"content\": \"Updated: Customer confirmed callback for Monday at 2pm.\"
}"

Example response:

{
    "data": {
        "uuid": "note-uuid-here",
        "content": "Updated: Customer confirmed callback for Monday at 2pm.",
        "created_by": {
            "uuid": "user-uuid",
            "name": "John Doe",
            "email": "[email protected]"
        },
        "updated_by": {
            "uuid": "user-uuid",
            "name": "John Doe",
            "email": "[email protected]"
        },
        "created_at": "2025-01-15T10:30:00+00:00",
        "updated_at": "2025-01-16T14:00:00+00:00"
    }
}

Delete Note

DELETE

https://api.surecontact.com

/api/v1/public/notes/{note_uuid}

requires authentication

Soft delete a note. Only the note creator or workspace managers can delete notes.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

note_uuid

string

required

Example:

77ce6a1f-5faa-4c6f-86ad-18a0963dc58e

note

string

required

The UUID of the note.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.surecontact.com/api/v1/public/notes/77ce6a1f-5faa-4c6f-86ad-18a0963dc58e" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[Empty response]

Custom Field Management

APIs for managing custom fields within a workspace. Custom fields allow extending contact data with workspace-specific attributes.

Get all custom fields

GET

https://api.surecontact.com

/api/v1/public/custom-fields

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Auth

Headers

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/custom-fields" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Show a specific custom field

GET

https://api.surecontact.com

/api/v1/public/custom-fields/{customField_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

customField_uuid

string

required

Example:

03e98771-493e-4c97-b446-026234075f69

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/custom-fields/03e98771-493e-4c97-b446-026234075f69" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

List Management

APIs for managing lists within a workspace. Lists can be static (manually managed) or dynamic (filter-based).

Get all lists

GET

https://api.surecontact.com

/api/v1/public/lists

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Auth

Headers

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/lists" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Show a specific list

GET

https://api.surecontact.com

/api/v1/public/lists/{list_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

list_uuid

string

required

Example:

52528ff6-afa6-488a-884c-59bd5ff748aa

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/lists/52528ff6-afa6-488a-884c-59bd5ff748aa" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Get contacts in a list (with runtime evaluation for dynamic lists)

GET

https://api.surecontact.com

/api/v1/public/lists/{list_uuid}/contacts

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

list_uuid

string

required

Example:

52528ff6-afa6-488a-884c-59bd5ff748aa

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/lists/52528ff6-afa6-488a-884c-59bd5ff748aa/contacts" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Create a new list

POST

https://api.surecontact.com

/api/v1/public/lists

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

The name of the list. Must be unique within the workspace. Must not be greater than 255 characters.

Example:

Newsletter Subscribers

description

string

Optional description for the list. Must not be greater than 1000 characters.

Example:

Contacts subscribed to our weekly newsletter

type

string

The type of list. "static" for manually managed lists, "dynamic" for filter-based lists.

Must be one of:

static
dynamic

Example:

static

filters

object

Filter criteria for dynamic lists. Only applicable when type is "dynamic".

Example:

[]

Auth

Headers

Body

{ "name": "Newsletter Subscribers", "description": "Contacts subscribed to our weekly newsletter", "type": "static", "filters": [] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/lists" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Newsletter Subscribers\",
    \"description\": \"Contacts subscribed to our weekly newsletter\",
    \"type\": \"static\",
    \"filters\": []
}"

Update a list

PUT

https://api.surecontact.com

/api/v1/public/lists/{list_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

list_uuid

string

required

Example:

52528ff6-afa6-488a-884c-59bd5ff748aa

Body Parameters

name

string

The name of the list. Must be unique within the workspace. Must not be greater than 255 characters.

Example:

Active Subscribers

description

string

Optional description for the list. Must not be greater than 1000 characters.

Example:

Contacts who are actively engaged with our content

type

string

The type of list. "static" for manually managed lists, "dynamic" for filter-based lists.

Must be one of:

static
dynamic

Example:

static

filters

object

Filter criteria for dynamic lists. Only applicable when type is "dynamic".

Example:

[]

Auth

Headers

URL Parameters

Body

{ "name": "Active Subscribers", "description": "Contacts who are actively engaged with our content", "type": "static", "filters": [] }

Received response

Example request:

curl --request PUT \
    "https://api.surecontact.com/api/v1/public/lists/52528ff6-afa6-488a-884c-59bd5ff748aa" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Active Subscribers\",
    \"description\": \"Contacts who are actively engaged with our content\",
    \"type\": \"static\",
    \"filters\": []
}"

Add contacts to a list

POST

https://api.surecontact.com

/api/v1/public/lists/{list_uuid}/contacts/add

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

list_uuid

string

required

Example:

52528ff6-afa6-488a-884c-59bd5ff748aa

Body Parameters

contact_uuids

string[]

A valid contact UUID. Must be a valid UUID. The uuid of an existing record in the contacts table.

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Auth

Headers

URL Parameters

Body

{ "contact_uuids": [ "550e8400-e29b-41d4-a716-446655440000" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/lists/52528ff6-afa6-488a-884c-59bd5ff748aa/contacts/add" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"contact_uuids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}"

Remove contacts from a list

POST

https://api.surecontact.com

/api/v1/public/lists/{list_uuid}/contacts/remove

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

list_uuid

string

required

Example:

52528ff6-afa6-488a-884c-59bd5ff748aa

Body Parameters

contact_uuids

string[]

A valid contact UUID. Must be a valid UUID. The uuid of an existing record in the contacts table.

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Auth

Headers

URL Parameters

Body

{ "contact_uuids": [ "550e8400-e29b-41d4-a716-446655440000" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/lists/52528ff6-afa6-488a-884c-59bd5ff748aa/contacts/remove" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"contact_uuids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}"

Delete a list

DELETE

https://api.surecontact.com

/api/v1/public/lists/{list_uuid}

requires authentication

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

list_uuid

string

required

Example:

52528ff6-afa6-488a-884c-59bd5ff748aa

Auth

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.surecontact.com/api/v1/public/lists/52528ff6-afa6-488a-884c-59bd5ff748aa" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Purchases

APIs for managing e-commerce purchases and order tracking. Purchases represent transactions made by contacts, tracked from various sources like WordPress/WooCommerce, Shopify, or via the API.

Purchase statuses: completed, cancelled, refunded, pending. Purchase sources: wordpress, shopify, api, manual.

Available via both authenticated API (Sanctum) and Public API (API Key).

List Purchases

GET

https://api.surecontact.com

/api/v1/public/purchases

requires authentication

Get paginated list of purchases for the workspace. Purchases are returned in reverse chronological order (newest first).

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

per_page

integer

Number of items per page (1-100). Default: 20.

Example:

page

integer

Page number.

Example:

status

string

Filter by purchase status.

Example:

completed

source

string

Filter by purchase source.

Example:

api

contact_uuid

string

Filter by contact UUID.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

per_page

integer

Must be at least 1. Must not be greater than 100.

Example:

page

integer

Must be at least 1.

Example:

status

string

Must be one of:

completed
cancelled
refunded
pending

Example:

refunded

source

string

Must be one of:

wordpress
shopify
api
manual

Example:

shopify

contact_uuid

string

Must be a valid UUID.

Example:

6b72fe4a-5b40-307c-bc24-f79acf9a1bb9

Auth

Headers

Query Parameters

Body

{ "per_page": 1, "page": 22, "status": "refunded", "source": "shopify", "contact_uuid": "6b72fe4a-5b40-307c-bc24-f79acf9a1bb9" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/purchases?per_page=20&page=1&status=completed&source=api&contact_uuid=550e8400-e29b-41d4-a716-446655440000" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"per_page\": 1,
    \"page\": 22,
    \"status\": \"refunded\",
    \"source\": \"shopify\",
    \"contact_uuid\": \"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\"
}"

Example response:

{
    "success": true,
    "data": [
        {
            "uuid": "purchase-uuid",
            "source": "api",
            "source_order_id": "ORD-12345",
            "status": "completed",
            "total_amount": 99.99,
            "currency": "USD",
            "products": [
                {
                    "name": "Product A",
                    "quantity": 1,
                    "price": 99.99
                }
            ],
            "purchased_at": "2025-01-15T10:30:00+00:00",
            "contact": {
                "uuid": "contact-uuid",
                "email": "[email protected]",
                "first_name": "John",
                "last_name": "Doe"
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 20,
        "total": 100
    }
}

Get Purchase

GET

https://api.surecontact.com

/api/v1/public/purchases/{purchase_uuid}

requires authentication

Retrieve a specific purchase by UUID.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

purchase_uuid

string

required

Example:

0db7aba5-50a0-4df6-9bb5-3177e247596b

purchase

string

required

The UUID of the purchase.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/purchases/0db7aba5-50a0-4df6-9bb5-3177e247596b" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "success": true,
    "data": {
        "uuid": "purchase-uuid",
        "source": "api",
        "source_order_id": "ORD-12345",
        "status": "completed",
        "total_amount": 99.99,
        "currency": "USD",
        "products": [
            {
                "name": "Product A",
                "quantity": 1,
                "price": 99.99
            }
        ],
        "metadata": {
            "payment_method": "credit_card",
            "shipping_amount": 5
        },
        "purchased_at": "2025-01-15T10:30:00+00:00",
        "contact": {
            "uuid": "contact-uuid",
            "email": "[email protected]"
        }
    }
}

Get Contact Purchases

GET

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/purchases

requires authentication

Retrieve purchase history for a specific contact, ordered by most recent first.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

contact

string

required

The UUID of the contact.

Example:

550e8400-e29b-41d4-a716-446655440000

Query Parameters

limit

integer

Maximum number of purchases to return (1-100). Default: 50.

Example:

Body Parameters

limit

integer

Must be at least 1. Must not be greater than 100.

Example:

Auth

Headers

URL Parameters

Query Parameters

Body

{ "limit": 1 }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/purchases?limit=50" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"limit\": 1
}"

Example response:

{
    "success": true,
    "data": [
        {
            "uuid": "purchase-uuid",
            "source": "api",
            "source_order_id": "ORD-12345",
            "status": "completed",
            "total_amount": 99.99,
            "currency": "USD",
            "purchased_at": "2025-01-15T10:30:00+00:00"
        }
    ],
    "meta": {
        "count": 5,
        "limit": 50
    }
}

Get Contact Purchase Stats

GET

https://api.surecontact.com

/api/v1/public/contacts/{contact_uuid}/purchase-stats

requires authentication

Retrieve purchase statistics for a specific contact including total purchases, total spent, average order value, and purchase date range.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

contact_uuid

string

required

Example:

00856ffe-26ce-4e9d-9800-b0fb67fb2e0e

contact

string

required

The UUID of the contact.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/contacts/00856ffe-26ce-4e9d-9800-b0fb67fb2e0e/purchase-stats" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "success": true,
    "data": {
        "total_purchases": 5,
        "total_spent": 499.95,
        "average_order_value": 99.99,
        "last_purchase_date": "2025-01-15T10:30:00+00:00",
        "first_purchase_date": "2024-06-01T14:00:00+00:00"
    }
}

Create Purchase

POST

https://api.surecontact.com

/api/v1/public/purchases

requires authentication

Track a new purchase for a contact. The contact can be identified by UUID or email. If using email and the contact doesn't exist, a new contact will be created automatically.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

contact_email

string

Email of the contact (required if contact_uuid not provided).

Example:

[email protected]

contact_uuid

string

UUID of the contact (required if contact_email not provided).

Example:

550e8400-e29b-41d4-a716-446655440000

order_id

string

required

Unique order identifier from your system.

Example:

ORD-12345

purchase_id

string

Optional secondary purchase identifier.

Example:

PUR-001

transaction_id

string

Payment transaction ID.

Example:

TXN-ABC123

status

string

Purchase status (completed, cancelled, refunded, pending). Default: completed.

Example:

completed

total_amount

number

required

Total order amount.

Example:

99.99

currency

string

Currency code (3 characters). Default: USD.

Example:

USD

products

string[]

List of products in the purchase.

product_id

string

Example:

architecto

name

string

Example:

architecto

quantity

integer

Must be at least 1.

Example:

price

number

Must be at least 0.

Example:

total

number

Must be at least 0.

Example:

sku

string

Example:

architecto

variation_id

string

Example:

architecto

object

product_id

string

Product identifier.

Example:

PROD-001

name

string

Product name.

Example:

Product A

quantity

integer

Quantity purchased.

Example:

price

number

Unit price.

Example:

99.99

total

number

Line total.

Example:

99.99

sku

string

Product SKU.

Example:

SKU-001

coupon_code

string

Applied coupon code.

Example:

SAVE10

coupon_amount

number

Coupon discount amount.

Example:

discount

number

Total discount amount.

Example:

shipping_amount

number

Shipping cost.

Example:

tax_amount

number

Tax amount.

Example:

8.5

subtotal

number

Subtotal before tax/shipping.

Example:

94.99

payment_method

string

Payment method used.

Example:

credit_card

shipping_method

string

Shipping method.

Example:

standard

customer_note

string

Customer notes for the order.

Example:

Please gift wrap

billing_address

object

Billing address details.

Example:

{"street":"123 Main St","city":"New York"}

shipping_address

object

Shipping address details.

Example:

{"street":"123 Main St","city":"New York"}

purchased_at

string

Purchase date (ISO 8601).

Example:

2025-01-15T10:30:00Z

metadata

object

Additional custom metadata.

Example:

{"custom_field":"value"}

Auth

Headers

Body

{ "contact_email": "[email protected]", "contact_uuid": "550e8400-e29b-41d4-a716-446655440000", "order_id": "ORD-12345", "purchase_id": "PUR-001", "transaction_id": "TXN-ABC123", "status": "completed", "total_amount": 99.99, "currency": "USD", "products": { "product_id": "architecto", "name": "architecto", "quantity": 22, "price": 84, "total": 12, "sku": "architecto", "variation_id": "architecto", "*": { "product_id": "PROD-001", "name": "Product A", "quantity": 1, "price": 99.99, "total": 99.99, "sku": "SKU-001" } }, "coupon_code": "SAVE10", "coupon_amount": 10, "discount": 10, "shipping_amount": 5, "tax_amount": 8.5, "subtotal": 94.99, "payment_method": "credit_card", "shipping_method": "standard", "customer_note": "Please gift wrap", "billing_address": { "street": "123 Main St", "city": "New York" }, "shipping_address": { "street": "123 Main St", "city": "New York" }, "purchased_at": "2025-01-15T10:30:00Z", "metadata": { "custom_field": "value" } }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/purchases" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"contact_email\": \"[email protected]\",
    \"contact_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",
    \"order_id\": \"ORD-12345\",
    \"purchase_id\": \"PUR-001\",
    \"transaction_id\": \"TXN-ABC123\",
    \"status\": \"completed\",
    \"total_amount\": 99.99,
    \"currency\": \"USD\",
    \"products\": [
        {
            \"name\": \"Product A\",
            \"quantity\": 1,
            \"price\": 99.99
        }
    ],
    \"coupon_code\": \"SAVE10\",
    \"coupon_amount\": 10,
    \"discount\": 10,
    \"shipping_amount\": 5,
    \"tax_amount\": 8.5,
    \"subtotal\": 94.99,
    \"payment_method\": \"credit_card\",
    \"shipping_method\": \"standard\",
    \"customer_note\": \"Please gift wrap\",
    \"billing_address\": {
        \"street\": \"123 Main St\",
        \"city\": \"New York\"
    },
    \"shipping_address\": {
        \"street\": \"123 Main St\",
        \"city\": \"New York\"
    },
    \"purchased_at\": \"2025-01-15T10:30:00Z\",
    \"metadata\": {
        \"custom_field\": \"value\"
    }
}"

$client = new \GuzzleHttp\Client();
$url = 'https://api.surecontact.com/api/v1/public/purchases';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-API-Key' => '{YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => \Symfony\Component\VarExporter\Internal\Hydrator::hydrate(
            $o = [
                clone (\Symfony\Component\VarExporter\Internal\Registry::$prototypes['stdClass'] ?? \Symfony\Component\VarExporter\Internal\Registry::p('stdClass')),
            ],
            null,
            [
                'stdClass' => [
                    'name' => [
                        'Product A',
                    ],
                    'quantity' => [
                        1,
                    ],
                    'price' => [
                        99.99,
                    ],
                ],
            ],
            [
                'contact_email' => '[email protected]',
                'contact_uuid' => '550e8400-e29b-41d4-a716-446655440000',
                'order_id' => 'ORD-12345',
                'purchase_id' => 'PUR-001',
                'transaction_id' => 'TXN-ABC123',
                'status' => 'completed',
                'total_amount' => 99.99,
                'currency' => 'USD',
                'products' => [
                    $o[0],
                ],
                'coupon_code' => 'SAVE10',
                'coupon_amount' => 10.0,
                'discount' => 10.0,
                'shipping_amount' => 5.0,
                'tax_amount' => 8.5,
                'subtotal' => 94.99,
                'payment_method' => 'credit_card',
                'shipping_method' => 'standard',
                'customer_note' => 'Please gift wrap',
                'billing_address' => [
                    'street' => '123 Main St',
                    'city' => 'New York',
                ],
                'shipping_address' => [
                    'street' => '123 Main St',
                    'city' => 'New York',
                ],
                'purchased_at' => '2025-01-15T10:30:00Z',
                'metadata' => [
                    'custom_field' => 'value',
                ],
            ],
            []
        ),
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response:

{
    "success": true,
    "message": "Purchase tracked successfully",
    "data": {
        "purchase_uuid": "purchase-uuid",
        "contact_uuid": "contact-uuid",
        "contact_email": "[email protected]",
        "order_id": "ORD-12345",
        "amount": "$99.99 USD",
        "status": "completed",
        "purchased_at": "2025-01-15T10:30:00+00:00"
    }
}

Cancel Purchase

POST

https://api.surecontact.com

/api/v1/public/purchases/{purchase_uuid}/cancel

requires authentication

Mark a purchase as cancelled. This updates the status to 'cancelled' and records the cancellation timestamp.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

purchase_uuid

string

required

Example:

0db7aba5-50a0-4df6-9bb5-3177e247596b

purchase

string

required

The UUID of the purchase to cancel.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/purchases/0db7aba5-50a0-4df6-9bb5-3177e247596b/cancel" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "success": true,
    "message": "Purchase cancelled successfully",
    "data": {
        "purchase_uuid": "purchase-uuid",
        "order_id": "ORD-12345",
        "status": "cancelled",
        "cancelled_at": "2025-01-15T12:00:00+00:00"
    }
}

Refund Purchase

POST

https://api.surecontact.com

/api/v1/public/purchases/{purchase_uuid}/refund

requires authentication

Mark a purchase as refunded. This updates the status to 'refunded' and records the refund timestamp.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

purchase_uuid

string

required

Example:

0db7aba5-50a0-4df6-9bb5-3177e247596b

purchase

string

required

The UUID of the purchase to refund.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/purchases/0db7aba5-50a0-4df6-9bb5-3177e247596b/refund" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "success": true,
    "message": "Purchase refunded successfully",
    "data": {
        "purchase_uuid": "purchase-uuid",
        "order_id": "ORD-12345",
        "status": "refunded",
        "cancelled_at": "2025-01-15T12:00:00+00:00"
    }
}

Reports

APIs for advanced analytics and reporting with date filtering, comparison periods, and export functionality.

Get reports overview

GET

https://api.surecontact.com

/api/v1/public/reports/overview

requires authentication

Returns high-level KPIs across contacts, emails, engagement, and revenue with optional comparison to previous period.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

90_days

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

previous_month

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

week

Auth

Headers

Body

{ "date_range": "90_days", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "previous_month", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "week" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/overview" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"90_days\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"previous_month\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"week\"
}"

Example response:

Get contact growth report

GET

https://api.surecontact.com

/api/v1/public/reports/contacts/growth

requires authentication

Returns contact growth statistics with optional filtering by tag or list.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

yesterday

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

previous_month

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

month

filter_type

string

Must be one of:

overall
tag
list

Example:

overall

filter_uuid

string

This field is required when filter_type is tag or list. Must be a valid UUID.

Example:

a4855dc5-0acb-33c3-b921-f4291f719ca0

Auth

Headers

Body

{ "date_range": "yesterday", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "previous_month", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "month", "filter_type": "overall", "filter_uuid": "a4855dc5-0acb-33c3-b921-f4291f719ca0" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/contacts/growth" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"yesterday\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"previous_month\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"month\",
    \"filter_type\": \"overall\",
    \"filter_uuid\": \"a4855dc5-0acb-33c3-b921-f4291f719ca0\"
}"

Example response:

Get email sending stats

GET

https://api.surecontact.com

/api/v1/public/reports/emails/sending

requires authentication

Returns email sending statistics including sent, delivered, failed, and bounced counts.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

12_months

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

custom

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

week

Auth

Headers

Body

{ "date_range": "12_months", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "custom", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "week" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/emails/sending" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"12_months\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"custom\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"week\"
}"

Example response:

Get email engagement stats

GET

https://api.surecontact.com

/api/v1/public/reports/emails/engagement

requires authentication

Returns email engagement statistics including opens, clicks, and rates.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

yesterday

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

none

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

day

Auth

Headers

Body

{ "date_range": "yesterday", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "none", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "day" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/emails/engagement" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"yesterday\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"none\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"day\"
}"

Example response:

Get link click analytics

GET

https://api.surecontact.com

/api/v1/public/reports/links/clicks

requires authentication

Returns top clicked links with total and unique click counts.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

90_days

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

previous_year

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

day

campaign_uuid

string

Must be a valid UUID.

Example:

6ff8f7f6-1eb3-3525-be4a-3932c805afed

limit

integer

Must be at least 1. Must not be greater than 500.

Example:

Auth

Headers

Body

{ "date_range": "90_days", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "previous_year", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "day", "campaign_uuid": "6ff8f7f6-1eb3-3525-be4a-3932c805afed", "limit": 7 }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/links/clicks" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"90_days\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"previous_year\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"day\",
    \"campaign_uuid\": \"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",
    \"limit\": 7
}"

Example response:

Get unsubscribe stats

GET

https://api.surecontact.com

/api/v1/public/reports/unsubscribes

requires authentication

Returns unsubscribe statistics with optional reasons breakdown.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

custom

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

previous_month

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

day

include_reasons

string

Auth

Headers

Body

{ "date_range": "custom", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "previous_month", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "day", "include_reasons": null }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/unsubscribes" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"custom\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"previous_month\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"day\"
}"

Example response:

Get bounce stats

GET

https://api.surecontact.com

/api/v1/public/reports/bounces

requires authentication

Returns bounce statistics with hard/soft bounce breakdown.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

90_days

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

none

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

week

bounce_type

string

Example:

architecto

Auth

Headers

Body

{ "date_range": "90_days", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "none", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "week", "bounce_type": "architecto" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/bounces" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"90_days\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"none\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"week\",
    \"bounce_type\": \"architecto\"
}"

Example response:

Get e-commerce revenue stats

GET

https://api.surecontact.com

/api/v1/public/reports/ecommerce/revenue

requires authentication

Returns revenue statistics including total revenue, orders, AOV, and trends.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

7_days

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

previous_year

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

day

source

string

Example:

architecto

Auth

Headers

Body

{ "date_range": "7_days", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "previous_year", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "day", "source": "architecto" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/ecommerce/revenue" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"7_days\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"previous_year\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"day\",
    \"source\": \"architecto\"
}"

Example response:

Get e-commerce product performance

GET

https://api.surecontact.com

/api/v1/public/reports/ecommerce/products

requires authentication

Returns top products by revenue and order count.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

12_months

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

none

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

month

limit

integer

Must be at least 1. Must not be greater than 100.

Example:

Auth

Headers

Body

{ "date_range": "12_months", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "none", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "month", "limit": 1 }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/ecommerce/products" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"12_months\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"none\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"month\",
    \"limit\": 1
}"

Example response:

Get campaign performance summary

GET

https://api.surecontact.com

/api/v1/public/reports/campaigns/summary

requires authentication

Returns aggregated metrics across all campaigns.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

custom

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

previous_period

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

month

status

string

Example:

architecto

Auth

Headers

Body

{ "date_range": "custom", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "previous_period", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "month", "status": "architecto" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/campaigns/summary" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"custom\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"previous_period\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"month\",
    \"status\": \"architecto\"
}"

Example response:

Export report data

GET

https://api.surecontact.com

/api/v1/public/reports/export

requires authentication

Downloads report data as CSV or Excel file.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

date_range

string

Must be one of:

today
yesterday
7_days
30_days
90_days
12_months
custom

Example:

7_days

start_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

end_date

string

This field is required when date_range is custom. Must be a valid date. Must be a date after or equal to start_date. Must be a date before or equal to today.

Example:

2022-02-15

compare_with

string

Must be one of:

none
previous_period
previous_month
previous_year
custom

Example:

custom

compare_start_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date before or equal to today.

Example:

2022-02-15

compare_end_date

string

This field is required when compare_with is custom. Must be a valid date. Must be a date after or equal to compare_start_date. Must be a date before or equal to today.

Example:

2022-02-15

group_by

string

Must be one of:

day
week
month

Example:

week

report_type

string

required

Must be one of:

contacts_growth
emails_sending
emails_engagement
link_clicks
unsubscribes
bounces
revenue
products
campaigns
overview

Example:

emails_engagement

format

string

required

Must be one of:

csv
xlsx

Example:

xlsx

filter_type

string

Must be one of:

overall
tag
list

Example:

tag

filter_uuid

string

This field is required when filter_type is tag or list. Must be a valid UUID.

Example:

a4855dc5-0acb-33c3-b921-f4291f719ca0

Auth

Headers

Body

{ "date_range": "7_days", "start_date": "2022-02-15", "end_date": "2022-02-15", "compare_with": "custom", "compare_start_date": "2022-02-15", "compare_end_date": "2022-02-15", "group_by": "week", "report_type": "emails_engagement", "format": "xlsx", "filter_type": "tag", "filter_uuid": "a4855dc5-0acb-33c3-b921-f4291f719ca0" }

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/reports/export" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"date_range\": \"7_days\",
    \"start_date\": \"2022-02-15\",
    \"end_date\": \"2022-02-15\",
    \"compare_with\": \"custom\",
    \"compare_start_date\": \"2022-02-15\",
    \"compare_end_date\": \"2022-02-15\",
    \"group_by\": \"week\",
    \"report_type\": \"emails_engagement\",
    \"format\": \"xlsx\",
    \"filter_type\": \"tag\",
    \"filter_uuid\": \"a4855dc5-0acb-33c3-b921-f4291f719ca0\"
}"

Example response:

Tag Management

APIs for managing tags within a workspace. Tags can be applied to contacts for categorization and segmentation purposes.

List Tags

GET

https://api.surecontact.com

/api/v1/public/tags

requires authentication

Get all tags for the current workspace with optional search and sorting.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Query Parameters

string

Search tags by name or slug.

Example:

newsletter

sort

string

Sort field. Allowed: name, slug, usage_count, created_at, updated_at.

Example:

name

direction

string

Sort direction: asc or desc. Default: asc.

Example:

asc

per_page

integer

Number of items per page. Default: 15.

Example:

Auth

Headers

Query Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/tags?search=newsletter&sort=name&direction=asc&per_page=20" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "uuid": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Newsletter",
            "slug": "newsletter",
            "color": "#3B82F6",
            "description": "Subscribed to newsletter",
            "usage_count": 150,
            "created_at": "2025-01-01T00:00:00+00:00"
        }
    ],
    "links": {},
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 10
    }
}

Get Tag

GET

https://api.surecontact.com

/api/v1/public/tags/{tag_uuid}

requires authentication

Get details of a specific tag.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

tag_uuid

string

required

Example:

f838174d-91d8-44e2-bc15-0ae2dc01a4f8

tag

string

required

The UUID of the tag.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/tags/f838174d-91d8-44e2-bc15-0ae2dc01a4f8" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "VIP Customer",
        "slug": "vip-customer",
        "color": "#10B981",
        "description": "High-value customers",
        "usage_count": 25,
        "created_at": "2025-01-01T00:00:00+00:00"
    }
}

Get Tag Contacts

GET

https://api.surecontact.com

/api/v1/public/tags/{tag_uuid}/contacts

requires authentication

Get all contacts that have this tag applied.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

tag_uuid

string

required

Example:

f838174d-91d8-44e2-bc15-0ae2dc01a4f8

tag

string

required

The UUID of the tag.

Example:

550e8400-e29b-41d4-a716-446655440000

Query Parameters

per_page

integer

Number of items per page. Default: 15.

Example:

Auth

Headers

URL Parameters

Query Parameters

Received response

Example request:

curl --request GET \
    --get "https://api.surecontact.com/api/v1/public/tags/f838174d-91d8-44e2-bc15-0ae2dc01a4f8/contacts?per_page=20" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

{
    "data": [
        {
            "uuid": "660e8400-e29b-41d4-a716-446655440001",
            "email": "[email protected]",
            "first_name": "John",
            "last_name": "Doe",
            "full_name": "John Doe",
            "phone": "+1234567890",
            "company": "Acme Inc",
            "job_title": "Manager",
            "source": "manual",
            "source_label": "Manual",
            "status": "active",
            "email_status": "valid",
            "created_at": "2025-01-01T00:00:00+00:00"
        }
    ],
    "links": {},
    "meta": {
        "current_page": 1,
        "per_page": 15,
        "total": 50
    }
}

Create Tag

POST

https://api.surecontact.com

/api/v1/public/tags

requires authentication

Create a new tag in the current workspace.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

name

string

required

The name of the tag. Max 255 characters.

Example:

VIP Customer

color

string

Hex color code for the tag.

Example:

#10B981

description

string

Optional description for the tag.

Example:

High-value customers

slug

string

The URL-friendly slug. Auto-generated from name if not provided.

Example:

vip-customer

Auth

Headers

Body

{ "name": "VIP Customer", "color": "#10B981", "description": "High-value customers", "slug": "vip-customer" }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/tags" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"VIP Customer\",
    \"color\": \"#10B981\",
    \"description\": \"High-value customers\",
    \"slug\": \"vip-customer\"
}"

Example response:

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "VIP Customer",
        "slug": "vip-customer",
        "color": "#10B981",
        "description": "High-value customers",
        "usage_count": 0,
        "created_at": "2025-01-15T10:30:00+00:00"
    }
}

Update Tag

PUT

https://api.surecontact.com

/api/v1/public/tags/{tag_uuid}

requires authentication

Update an existing tag's details.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

tag_uuid

string

required

Example:

f838174d-91d8-44e2-bc15-0ae2dc01a4f8

tag

string

required

The UUID of the tag.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

name

string

The name of the tag. Max 255 characters.

Example:

Premium Customer

color

string

Hex color code for the tag.

Example:

#F59E0B

description

string

Description for the tag.

Example:

Premium tier customers

slug

string

The URL-friendly slug.

Example:

premium-customer

Auth

Headers

URL Parameters

Body

{ "name": "Premium Customer", "color": "#F59E0B", "description": "Premium tier customers", "slug": "premium-customer" }

Received response

Example request:

curl --request PUT \
    "https://api.surecontact.com/api/v1/public/tags/f838174d-91d8-44e2-bc15-0ae2dc01a4f8" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Premium Customer\",
    \"color\": \"#F59E0B\",
    \"description\": \"Premium tier customers\",
    \"slug\": \"premium-customer\"
}"

Example response:

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Premium Customer",
        "slug": "premium-customer",
        "color": "#F59E0B",
        "description": "Premium tier customers",
        "usage_count": 25,
        "created_at": "2025-01-01T00:00:00+00:00"
    }
}

Add Contacts to Tag

POST

https://api.surecontact.com

/api/v1/public/tags/{tag_uuid}/contacts/add

requires authentication

Add multiple contacts to a tag. Contacts that already have the tag will be skipped. Maximum 10,000 contacts per request.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

tag_uuid

string

required

Example:

f838174d-91d8-44e2-bc15-0ae2dc01a4f8

tag

string

required

The UUID of the tag.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

contact_uuids

string[]

required

Array of contact UUIDs to add to the tag. Max 10,000 items.

Example:

["660e8400-e29b-41d4-a716-446655440001","770e8400-e29b-41d4-a716-446655440002"]

Auth

Headers

URL Parameters

Body

{ "contact_uuids": [ "660e8400-e29b-41d4-a716-446655440001", "770e8400-e29b-41d4-a716-446655440002" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/tags/f838174d-91d8-44e2-bc15-0ae2dc01a4f8/contacts/add" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"contact_uuids\": [
        \"660e8400-e29b-41d4-a716-446655440001\",
        \"770e8400-e29b-41d4-a716-446655440002\"
    ]
}"

Example response:

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "VIP Customer",
        "slug": "vip-customer",
        "color": "#10B981",
        "description": "High-value customers",
        "usage_count": 27,
        "created_at": "2025-01-01T00:00:00+00:00"
    }
}

Remove Contacts from Tag

POST

https://api.surecontact.com

/api/v1/public/tags/{tag_uuid}/contacts/remove

requires authentication

Remove multiple contacts from a tag. Contacts that don't have the tag will be skipped. Maximum 10,000 contacts per request.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

tag_uuid

string

required

Example:

f838174d-91d8-44e2-bc15-0ae2dc01a4f8

tag

string

required

The UUID of the tag.

Example:

550e8400-e29b-41d4-a716-446655440000

Body Parameters

contact_uuids

string[]

required

Array of contact UUIDs to remove from the tag. Max 10,000 items.

Example:

["660e8400-e29b-41d4-a716-446655440001","770e8400-e29b-41d4-a716-446655440002"]

Auth

Headers

URL Parameters

Body

{ "contact_uuids": [ "660e8400-e29b-41d4-a716-446655440001", "770e8400-e29b-41d4-a716-446655440002" ] }

Received response

Example request:

curl --request POST \
    "https://api.surecontact.com/api/v1/public/tags/f838174d-91d8-44e2-bc15-0ae2dc01a4f8/contacts/remove" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"contact_uuids\": [
        \"660e8400-e29b-41d4-a716-446655440001\",
        \"770e8400-e29b-41d4-a716-446655440002\"
    ]
}"

Example response:

{
    "data": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "VIP Customer",
        "slug": "vip-customer",
        "color": "#10B981",
        "description": "High-value customers",
        "usage_count": 23,
        "created_at": "2025-01-01T00:00:00+00:00"
    }
}

Delete Tag

DELETE

https://api.surecontact.com

/api/v1/public/tags/{tag_uuid}

requires authentication

Permanently delete a tag. This will remove the tag from all contacts.

Headers

X-API-Key

Example:

{YOUR_API_KEY}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

tag_uuid

string

required

Example:

f838174d-91d8-44e2-bc15-0ae2dc01a4f8

tag

string

required

The UUID of the tag.

Example:

550e8400-e29b-41d4-a716-446655440000

Auth

Headers

URL Parameters

Received response

Example request:

curl --request DELETE \
    "https://api.surecontact.com/api/v1/public/tags/f838174d-91d8-44e2-bc15-0ae2dc01a4f8" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

[Empty response]