API Documentation

Version 1 of the Spoki API is structured around REST, HTTP, and JSON. API endpoint URLs are organized around resources, such as contacts or deals. It uses HTTP methods for indicating the action to take on a resource, and HTTP status codes for expressing error states. Resources are represented in JSON following a conventional schema.

				
					curl -H "X-Spoki-Api-Key: YOUR_API_KEY" https://app.spoki.it/api/1/
				
			
  • The API is accessed using the base URL follow: app.spoki.it/api/1/
  • URL paths must begin with /api/1 to specify version 1 of the API.
  • The URL will be in the form https://app.spoki.it/api/1/
  • All API calls should be made over HTTPS.

All requests to the API are authenticated by providing your API key. The API key must be provided as an HTTP header named X-Spoki-Api-Key.

Each Spoki account has his own unique API key.

The v1 API uses standard HTTP methods for indicating the action to take on a resource.

MethodAction
GETRetrieve a resource.
POSTCreate a new resource.
PATCHUpdate a resource (including partial updates).
DELETERemove a resource.

All API requests and response bodies adhere to a common JSON format representing individual items, collections of items, links to related items and additional meta data.

Single Resources

Individual resources are represented by top level member named after the resource in the singular form.

Collections

Collections of resources are represented by a top level member named after the resource in the plural form.

The API uses HTTP status codes to indicate an error has occurred while processing a request. There are four main error status codes used by the API:

CodeDescription
401The request could not be authenticated or the authenticated user is not authorized to access the requested resource.
404The requested resource does not exist.
400The request could not be processed, usually due to a missing or invalid parameter.
429The user has sent too many requests in a given amount of time ("rate limiting").

To ensure the best experience with using the ActiveCampaign APIs, please observe the following guidelines.

  • Use version 1 (v1) APIs.
  • If an error occurs, please pause or “sleep” execution for at least 1,000 milliseconds before resubmitting your API request.

We are actively working on improving our platform experience, adding new features, and improving performance. Following these guidelines will reduce intermittent errors and help us to provide a better experience for all customers.

This endpoint allows you to start an automation created on Spoki Platform.

Important: You don’t need the API_KEY to use this API. Just get the WEBHOOK_SECRET from the Automation Detail as shown below.

				
					POST https://app.spoki.it/wh/ap/{WEBHOOK_UUID}/
				
			
				
					Request Payload

{
	"secret": "{WEBHOOK_SECRET}", // required
	"phone": "+393331234567", // required
	"first_name": "Mario",
	"last_name": "Rossi",
	"email": "mario.rossi@example.com",
	"custom_fields": {
        "ORDER_ID": "12231",
        "TRACKING_NUMBER": "12231huh23b2"
    }
}
				
			
				
					Response 200 OK


{
    "success": true
}
				
			
				
					import requests

data = {'secret': 'WEBHOOK_SECRET', 'phone': '+393331234567'}
url = 'https://app.spoki.it/wh/ap/WEBHOOK_UUID/'
r = requests.post(url, json=data)
print(r.text)
				
			

This endpoint allows you to send a transactional WhatsApp message.

Important: Make sure the the template for the massage has already been approved by WhatsApp.

				
					POST https://app.spoki.it/business/api/send/{SERVICE_API_KEY}/
				
			
				
					Request Payload

{
	"phone": "+393331234567", // required
	"first_name": "Mario",
	"last_name": "Rossi",
	"text": "Hi Mario, your order #1234 has been shipped.",  // required
}
				
			
				
					Response 200 OK


{
    "success": true
}
				
			
				
					import requests

data = {'text': 'Hi Mario, your order #1234 has been shipped.', 'phone': '+393331234567'}
url = 'https://app.spoki.it/business/api/send/SERVICE_API_KEY/'
r = requests.post(url, json=data)
print(r.text)
				
			

Receive Webhook From Spoki when a contact reaches the step.

				
					POST {YOUR_DELIVERY_URL}
				
			
				
					Request Payload

{
   "contact": {
        "id": 10,
        "phone": "+393331234567",
        "first_name": "Mario",
        "last_name": "Rossi",
        "email": "mario.rossi@example.com",
        "chat_link":"https://spoki.app/chats/fV1raxSvcEqOG6KSXOk4",
        "contactfield_set": [
            {
                "filed": 13,
                "visual_code": "%%CITY%%",
                "value": "Milano"
            }
        ]
    }
}
				
			
				
					Expected Response 

200 OK
				
			
				
					POST contacts/sync/
				
			
				
					Request Payload

[
    {
    	"phone": "+393331234567", // required
    	"first_name": "Mario",
    	"last_name": "Rossi",
    	"email": "mario.rossi@example.com",
    	"language": "it" // optional: it will be set automatically if not sent based on phone prefix
    }
]
				
			
				
					Response 200 OK

[
    {
        "id": 10,
    	"phone": "+393331234567",
    	"first_name": "Mario",
    	"last_name": "Rossi",
    	"email": "mario.rossi@example.com",
    	"language": "it",
        "contactfield_set": [
    	    {
    	        "filed": 13,
    	        "value": "Milano"
    	    }
    	]
    }
]
				
			
				
					GET contacts/:id/
				
			
				
					curl --request GET \
     --url https://app.spoki.it/api/1/contacts/10/ \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{
    "id": 10,
	"phone": "+393331234567",
	"first_name": "Mario",
	"last_name": "Rossi",
	"email": "mario.rossi@example.com",
	"language": "it",
	"has_invalid_phone": false,
    "contactfield_set": [],
    "list_set": [],
    "tag_set": [],
    "chat_link": "https://spoki.app/chats/VSBpASVZ9kDKctAV3eUb",
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					PATCH contacts/:id/
				
			
				
					Request Payload

{
	"last_name": "Rossini",
	"contactfield_set": [
	    {
	        "filed": 13,
	        "value: "Milano"
	    }
	]
}
				
			
				
					Response 200 OK

{
    "id": 10,
	"phone": "+393331234567",
	"first_name": "Mario",
	"last_name": "Rossini",
	"email": "mario.rossi@example.com",
	"language": "it",
    "contactfield_set": [
	    {
	        "filed": 13,
	        "value": "Milano"
	    }
	]
}
				
			
				
					DELETE contacts/:id/
				
			
				
					curl --request DELETE \
     --url https://app.spoki.it/api/1/contacts/10/ \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{}
				
			
				
					GET contacts/
				
			
				
					import requests
headers = {"X-Spoki-Api-Key": "API_KEY"}
params = {"page_size": 100, "page": 1}
r = requests.get("https://app.spoki.it/api/1/contacts/", headers=headers, params=params )
print(r.json())
				
			
				
					curl --request GET \
     --url https://app.spoki.it/api/1/contacts/?page_size=100&page=1 \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 10,
        	"phone": "+393331234567",
        	"first_name": "Mario",
        	"last_name": "Rossi",
        	"email": "mario.rossi@example.com",
        	"language": "it",
        	"has_invalid_phone": false,
            "contactfield_set": [
        	    {
        	        "filed": 13,
        	        "value": "Milano"
        	    }
        	],
            "list_set": [],
            "tag_set": [],
            "chat_link": "https://spoki.app/chats/VSBpASVZ9kDKctAV3eUb",
            "created_datetime": "2021-12-13T15:46:54.115482+01:00"
        }
    ]
}
				
			
				
					POST lists/
				
			
				
					Request Payload

{
    "name": "Newsletter" // required
}
				
			
				
					Response 201 Created

{
    "id": 17,
    "name": "Newsletter",
    "contacts_count": 0,
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					GET lists/:id/
				
			
				
					curl --request GET \
     --url https://app.spoki.it/api/1/lists/17/ \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{
    "id": 17,
    "name": "Newsletter",
    "contacts_count": 0,
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					PATCH lists/:id/
				
			
				
					Request Payload

{
    "name": "Newsletter 2"
}
				
			
				
					Response 200 OK

{
    "id": 17,
    "name": "Newsletter 2",
    "contacts_count": 0,
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					DELETE lists/:id/
				
			
				
					curl --request DELETE \
     --url https://app.spoki.it/api/1/lists/17/ \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{}
				
			
				
					GET lists/
				
			
				
					import requests
headers = {"X-Spoki-Api-Key": "API_KEY"}
params = {"page_size": 100, "page": 1}
r = requests.get("https://app.spoki.it/api/1/lists/", headers=headers, params=params )
print(r.json())
				
			
				
					curl --request GET \
     --url https://app.spoki.it/api/1/lists/?page_size=100&page=1 \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 17,
            "name": "Newsletter",
            "contacts_count": 0,
            "created_datetime": "2021-12-13T15:46:54.115482+01:00"
        }
    ]
}
				
			
				
					POST lists/:id/sync_contacts/
				
			
				
					Request Payload

[
    {
    	"phone": "+393331234567", // required
    	"first_name": "Mario",
    	"last_name": "Rossi",
    	"email": "mario.rossi@example.com"
    }
]
				
			
				
					Response 200 OK

{
    "id": 17,
    "name": "Newsletter",
    "contacts_count": 1,
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					POST lists/:id/remove_contacts/
				
			
				
					Request Payload

{
    "contacts": [10]
}
				
			
				
					Response 200 OK

{
    "id": 17,
    "name": "Newsletter",
    "contacts_count": 0,
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					POST lists/:id/remove_all_contacts/
				
			
				
					Request Payload

{}
				
			
				
					Response 200 OK

{
    "id": 17,
    "name": "Newsletter",
    "contacts_count": 0,
    "created_datetime": "2021-12-13T15:46:54.115482+01:00"
}
				
			
				
					POST custom-fields/
				
			
				
					Request Payload

{
    "label": "Date of birth",
    "code": "DATE_OF_BIRTH" // use UPPER_CASE
}
				
			
				
					Response 201 Created

{
    "id": 42,
    "label": "Date of birth",
    "code": "DATE_OF_BIRTH"
}
				
			
				
					POST custom-fields/:id/
				
			
				
					curl --request GET \
     --url https://app.spoki.it/api/1/custom-fields/42/ \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{
    "id": 42,
    "label": "Date of birth",
    "code": "DATE_OF_BIRTH"
}
				
			
				
					PATCH custom-fields/:id/
				
			
				
					Request Payload

{
    "label": "Birthday"
}
				
			
				
					Response 200 OK

{
    "id": 42,
    "label": "Birthday",
    "code": "DATE_OF_BIRTH"
}
				
			
				
					DELETE custom-fields/:id/
				
			
				
					curl --request DELETE \
     --url https://app.spoki.it/api/1/custom-fields/42/ \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{}
				
			
				
					GET custom-fields/
				
			
				
					import requests
headers = {"X-Spoki-Api-Key": "API_KEY"}
params = {"page_size": 100, "page": 1}
r = requests.get("https://app.spoki.it/api/1/contact-fields/", headers=headers, params=params )
print(r.json())
				
			
				
					curl --request GET \
     --url https://app.spoki.it/api/1/contact-fields/?page_size=100&page=1 \
     --header 'Accept: application/json' \
     --header "X-Spoki-Api-Key: YOUR_API_KEY"
				
			
				
					Response 200 OK

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 42,
            "label": "Birthday",
            "code": "DATE_OF_BIRTH"
        }
    ]
}