Introduction

Welcome to the Closum API! You can use our API to access Closum API endpoints, which can retrieve any data associated with your account.

We have language bindings in Shell, Ruby, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

# With shell, you can just pass the correct header with each request
curl -X POST \
  https://api.closum.com/api/token \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_username":"your-closum-api-username",
    "api_pw":"your-closum-api-pw"
   }'

{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjEsImV4cCI6MTUyNjA1OTI0M30.kwFyE1ipf78f6BJafnj0ED3m4wcYWAM70B0t065jUd0",
        "expires_in": 604800,
        "expiration_date": "2018-05-11T17:20:43+00:00"
    }
}

Closum uses Bearer Tokens to allow access to the API. Those are set with a lifetime as set on the field "expires_in" and you should refresh your Bearer Tokens within the returned "expiration_date".

Closum expects for the Bearer Token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer your.bearer.token

You must replace your.bearer.token with your personal Bearer Token.

Querystring Parameters

Our API comes with support for querystring parameters that you can use to manipulate the output produced by our API.

Parameter	Default	Description
limit	`25`	If set, `limit` parameter will manipulate the number of records returned.
page	`1`	If set, `page` parameter will retrieve records from another page.
sort	`id`	If set, `sort` parameter will specify which field should be used to sort the results produced.
direction	`asc`	This parameter in combination with the `sort` parameter to specify the direction in which results are sorted.

Leads

Lead Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to lead
name	string	False	The name relative to lead
contact_lifecycle_stage_id	integer	False	The contact_lifecycle_stage_id relative to lead
custom_data	string	False	A JSON formated string containing extra fields
creation_date	date-time	True	The creation_date of the record
phone	object	False	The phone object associated to lead
email	object	False	The email object associated to lead
lead_opt_in	object	False	The lead_opt_in object associated to lead

List All Leads

curl -X GET \
https://api.closum.com/api/lead \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
      "success": true,
      "data": [
            {
                  "id": 1,
                  "name": "Sylvia L. Hook",
                  "contact_lifecycle_stage_id": 1,
                  "custom_data": null,
                  "creation_date": "2018-01-01T10:00:00+00:00",
                  "phone": {
                        "extension" : "001",
                        "number": "517-388-1452"
                  },
                  "email": {
                        "email": "[email protected]"
                  }
            },
            {
                  ...
            },
      ],
      "pagination": {
            "page_count": 1001,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 25025,
            "limit": null
      }
}

This endpoint retrieves all leads associated with your account.

HTTP Request

GET https://api.closum.com/api/lead

Create a New Lead

curl -X POST \
https://api.closum.com/api/lead \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "name": "Sylvia L. Hook",
    "email" : {"email" : "[email protected]"},
    "phone" : {"extension" : "001","number" : "517-388-1452"},
    "lead_opt_in" : {
        "sms" : true,
        "email" : true,
        "enviroment" : {
            "CONTENT_LENGTH" : "222",
            "HTTP_USER_AGENT" : "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0",
            "HTTP_REFERER" : "https://www.google.com",
            "HTTP_ACCEPT_LANGUAGE" : "pt-PT,pt;q=0.8,en;q=0.5,en-US;q=0.3",
            "REMOTE_ADDR" : "192.168.1.1",
            "REMOTE_PORT" : "1364",
            "REQUEST_URI" : "/",
            "REQUEST_TIME_FLOAT" : "1547548827.898"
        }
    }
}'

{
      "success": true,
      "data": {
            "id": 1
      }
}

This endpoint allows you to add a new Lead.

HTTP Request

POST https://api.closum.com/api/lead

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
name	The name of lead.
email	A JSON email object
phone	A JSON phone object.
lead_opt_in	A JSON lead_opt_in object
contact_lifecycle_stage_id	integer
custom_data	string

Retrieve a Lead

curl -X GET \
https://api.closum.com/api/lead/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
      "success": true,
      "data": {
            "id": 1,
            "name": "Sylvia L. Hook",
            "creation_date": "2015-12-30T19:31:14+00:00",
            "contact_lifecycle_stage_id": 1,
            "custom_data": null,
            "email": {
                  "id" : 1,
                  "email": "[email protected]"
            },
            "phone": {
                  "id": 1,
                  "extension" : "001",
                  "number": "517-388-1452"
            }
      }
}

This endpoint retrieves a specific Lead.

HTTP Request

GET https://api.closum.com/api/lead/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Lead to retrieve

Audience List

Audience List Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to audience_list
name	string	False	The name that identifies the audience_list
creation_date	date-time	Yes	The creation_date of the record

List All Audience List

curl -X GET \
https://api.closum.com/api/audience-list \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
      "success": true,
      "data": [
          {
              "id": 289743,
              "name": "My First Audience List",
              "creation_date": "2020-07-20T18:15:55+00:00"
          },
          {
              ...
          }
      ],
      "pagination": {
            "page_count": 100,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 2500,
            "limit": null
      }
}

This endpoint retrieves all audience_list records in your company.

HTTP Request

GET https://api.closum.com/api/audience-list

Create an Audience List

curl -X POST \
https://api.closum.com/api/audience-list \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "name": "My First Audience List"
}'

{
      "success": true,
      "data": {
            "id": 1
      }
}

This endpoint allows you to create a new audience_list.

HTTP Request

POST https://api.closum.com/api/audience-list

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
name	The name that identifies the audience_list

Retrieve an Audience List

curl -X GET \
https://api.closum.com/api/audience-list/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
    "success": true,
    "data": {
        "id": 1,
        "name": "My First Audience List",
        "creation_date": "2020-07-20T18:15:55+00:00"
    }
}

This endpoint retrieves a specific Audience List.

HTTP Request

GET https://api.closum.com/api/audience-list/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Audience List to retrieve

Lead Audience List

Lead Audience List Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to lead_audience_list
lead_id	integer	False	The lead_id that we pretend to add to the audience_list
audience_list_id	integer	False	The audience_list_id that we pretend to add the lead_id
creation_date	date-time	Yes	The creation_date of the record

List All Lead Audience List

curl -X GET \
https://api.closum.com/api/lead-audience-list \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
      "success": true,
      "data": [
            {
            "id": 289743,
                "lead_id": 1,
                "audience_list_id": 924,
                "creation_date": "2020-07-20T18:15:55+00:00"
            },
            {
                  ...
            }
      ],
      "pagination": {
            "page_count": 100,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 2500,
            "limit": null
      }
}

This endpoint retrieves all lead associated with audience_list in your company.

HTTP Request

GET https://api.closum.com/api/lead-audience-list

Create a Lead Audience List

curl -X POST \
https://api.closum.com/api/lead-audience-list \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "lead_id": 1,
    "audience_list_id": 924
}'

{
      "success": true,
      "data": {
            "id": 1
      }
}

This endpoint allows you to add a lead to an audience_list.

HTTP Request

POST https://api.closum.com/api/lead-audience-list

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
lead_id	The lead_id to add to an audience_list
audience_list_id	The audience_list_id to add to the lead

Retrieve a Lead Audience List

curl -X GET \
https://api.closum.com/api/lead-audience-list/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
    "success": true,
    "data": {
        "id": 1,
        "lead_id": 1,
        "audience_list_id": 924,
        "creation_date": "2020-07-20T18:15:55+00:00"
    }
}

This endpoint retrieves a specific Lead Audience List.

HTTP Request

GET https://api.closum.com/api/lead-audience-list/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Lead Audience List to retrieve

Emails

Email Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to email
email	string	False	The email address to insert
status	integer	Yes	The activation status relative to email
register_date	date-time	Yes	The register_date of the record

List All Emails

curl -X GET \
https://api.closum.com/api/email \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
      "success": true,
      "data": [
            {
                  "id": 1,
                  "email": "[email protected]",
                  "status": 1,
                  "register_date": "2018-01-01T01:01:01+00:00"
            },
            {
                  ...
            }
      ],
      "pagination": {
            "page_count": 100,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 2500,
            "limit": null
      }
}

This endpoint retrieves all emails associated with your account.

HTTP Request

GET https://api.closum.com/api/email

Create a New Email

curl -X POST \
https://api.closum.com/api/email \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
      "email" : "[email protected]"
}'

{
      "success": true,
      "data": {
            "id": 1
      }
}

This endpoint allows you to add a new Email.

HTTP Request

POST https://api.closum.com/api/email

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
email	The email address to insert

Retrieve an Email

curl -X GET \
https://api.closum.com/api/email/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

{
      "success": true,
      "data": {
            "id": 1,
            "email": "[email protected]",
            "status": 1,
            "register_date": "2018-01-01T01:01:01+00:00"
      }
}

This endpoint retrieves a specific Email.

HTTP Request

GET https://api.closum.com/api/email/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Email to retrieve

Update an Email

curl -X PUT \
https://api.closum.com/api/email/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
      "id" : 1,
      "email": "[email protected]"
}'

{
      "success": true,
      "data": []
}

This endpoint updates a specific Email.

HTTP Request

PUT https://api.closum.com/api/email/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Email to update

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
email	The new email address

Phones

Phone Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to phone
extension	string	False	The phone extension associated with country
number	string	False	The phone number
is_valid	boolean	Yes	The phone validation status
date_add	date-time	Yes	The register_date of the record

List All Phones

curl -X GET \
https://api.closum.com/api/phone \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json'

{
      "success": true,
      "data": [
            {
                  "id": 1,
                  "extension": "001",
                  "number": "517-388-1452",
                  "is_valid": 1,
                  "date_add": "2018-01-01T10:00:00+00:00"
            },
            {
                  ...
            }
      ],
      "pagination": {
            "page_count": 10,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 250,
            "limit": null
      }
}

This endpoint retrieves all phones associated with your account.

HTTP Request

GET https://api.closum.com/api/phone

Create a New Phone

curl -X POST \
curl -X POST \
https://api.closum.com/api/phone \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
      "extension": "001",
      "number": "517-388-1452"
}'

{
      "success": true,
      "data": {
            "id": 1
      }
}

This endpoint allows you to add a new Phone.

HTTP Request

POST https://api.closum.com/api/phone

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
extension	The phone extension associated with country
number	The phone number

Retrieve a Phone

curl -X GET \
https://api.closum.com/api/phone/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json'

{
      "success": true,
      "data": {
            "id": 1,
            "extension": "001",
            "number": "517-388-1452",
            "is_valid": 1,
            "date_add": "2018-01-01T10:00:00+00:00"
      }
}

This endpoint retrieves a specific Phone.

HTTP Request

GET https://api.closum.com/api/phone/<ID>

URL Parameters

Parameter	Description
ID	The ID of Phone to retrieve

Update a Phone

curl -X PUT \
https://api.closum.com/api/phone/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
      "id" : 1,
      "extension": "001",
      "number": "517-388-1452"
}'

{
      "success": true,
      "data": []
}

This endpoint updates a specific Phone.

HTTP Request

PUT https://api.closum.com/api/phone/<ID>

URL Parameters

Parameter	Description
ID	The ID of Phone to update

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
extension	The phone extension associated with country
number	The phone number

Contact Lifecycle Stages

Contact Lifecycle Stages Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to contact lifecycle stage
label	string	True	The designation of contact lifecycle stage

List All Contact Lifecycle Stages

curl -X GET \
https://api.closum.com/api/contact-lifecycle-stage/ \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json'

{
    "success": true,
    "data": [
        {
            "id": 1,
            "label": "Não Qualificado"
        },
        {
            "id": 2,
            "label": "Subscritor"
        },
        {
            "id": 3,
            "label": "Lead"
        },
        {
            "id": 4,
            "label": "Marketing Qualified Lead"
        },
        {
            "id": 5,
            "label": "Sales Qualified Lead"
        },
        {
            "id": 6,
            "label": "Oportunidade"
        },
        {
            "id": 7,
            "label": "Cliente"
        },
        {
            "id": 8,
            "label": "Evangelista"
        },
        {
            "id": 9,
            "label": "Outro"
        }
    ],
    "pagination": {
        "page_count": 1,
        "current_page": 1,
        "has_next_page": false,
        "has_prev_page": false,
        "count": 9,
        "limit": null
    }
}

This endpoint retrieves all contact lifecycle stages.

HTTP Request

GET https://api.closum.com/api/contact-lifecycle-stage/

Lead Opt In

Lead Opt In Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to lead opt in
lead_id	integer	True	The lead_id which the lead opt in belong to
sms	boolean	False	Consent status for SMS marketing
email	boolean	False	Consent status for EMAIL marketing
enviroment	string	False	A JSON enviroment object
creation_date	date-time	True	The creation_date of the record

Enviroment Properties

Parameter	Type	Read Only	Description
CONTENT_LENGTH	string	False	The Content-Length entity header is indicating the size of the entity-body, in bytes, sent to the recipient.
HTTP_USER_AGENT	string	False	The User-Agent containing network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent.
HTTP_REFERER	string	False	The Referer request header contains the address of the previous web page from which a link to the currently requested page was followed.
HTTP_ACCEPT_LANGUAGE	string	False	The Accept-Language request HTTP header advertises which languages the client is able to understand, and which locale variant is preferred.
REMOTE_ADDR	string	False	The IP address of the remote host.
REMOTE_PORT	string	False	The Port being used on the user's machine to communicate with the web server.
REQUEST_URI	string	False	The URI which was given in order to access this page.
REQUEST_TIME_FLOAT	string	False	The timestamp of the start of the request, with microsecond precision.

Errors

The Closum API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your Bearer Token is wrong.
403	Forbidden -- You don't have permission to access this request on this server.
404	Not Found -- The specified record could not be found.
405	Method Not Allowed -- You tried to access with an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.