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
city_id	integer	False	The city_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",
                  "city_id": 40,
                  "custom_data": null,
                  "creation_date": "2018-01-01T10:00:00+00:00",
                  "phone": {
                        "extension" : "001",
                        "number": "517-388-1452"
                  },
                  "email": {
                        "email": "sylvialhook@closum.com"
                  }
            },
            {
                  ...
            },
      ],
      "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" : "sylvialhook@closum.com"},
    "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
city_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",
            "city_id": 1,
            "custom_data": null,
            "email": {
                  "id" : 1,
                  "email": "sylvialhook@closum.com"
            },
            "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

Unqualified Lead (Contact)

Unqualified Lead Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to unqualified lead
name	string	False	The name relative to unqualified lead
phone	object	False	The phone object associated to unqualified lead
email	object	False	The email object associated to unqualified lead
contact_type_id	integer	False	The contact_type_id relative to unqualified lead
unqualified_lead_opt_in	object	False	The unqualified_lead_opt_in object associated to unqualified lead

List All Unqualified Leads

curl -X GET \
https://api.closum.com/api/unqualified-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_type_id": 1,
                  "city_id": 40,
                  "creation_date": "2018-01-01T10:00:00+00:00",
                  "phone": {
                        "number": "517-388-1452"
                  },
                  "email": {
                        "email": "sylvialhook@closum.com"
                  }
            },
            {
                  ...
            },
      ],
      "pagination": {
            "page_count": 1001,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 25025,
            "limit": null
      }
}

This endpoint retrieves all unqualified leads associated with your account.

HTTP Request

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

Create a New Unqualified Lead

curl -X POST \
https://api.closum.com/api/unqualified-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" : "sylvialhook@closum.com"},
    "phone" : {"extension" : "001","number" : "517-388-1452"},
    "contact_type_id": "1",
    "unqualified_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": 1001
    }
}

This endpoint allows you to add a new Unqualified Lead.

HTTP Request

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

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
name	The name of unqualified lead.
email	A JSON email object
phone	A JSON phone object.
unqualified_lead_opt_in	A JSON unqualified_lead_opt_in object
contact_type_id	integer

Retrieve an Uqualified Lead

curl -X GET \
https://api.closum.com/api/unqualified-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": 1001,
        "name": "Sylvia L. Hook",
        "contact_type_id": 1,
        "city_id": 1,
        "creation_date": "2018-01-01T12:56:19+00:00",
        "phone": {
            "number": "916912468"
        },
        "email": {
            "email": "sylvialhook@closum.com"
        }
    }
}

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

Cities

List All Cities

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

{
      "success": true,
      "data": [
            {
                  "id": 213,
                  "city_name": "Abrantes"
            },
            {
                  ...
            }
      ],
      "pagination": {
            "page_count": 13,
            "current_page": 1,
            "has_next_page": true,
            "has_prev_page": false,
            "count": 308,
            "limit": null
      }
}

This endpoint retrieves all leads associated with your account.

HTTP Request

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

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": "sylvialhook@closum.com",
                  "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" : "sylvialhook@closum.com"
}'

{
      "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": "sylvialhook@closum.com",
            "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": "update.sylvialhook@closum.com"
}'

{
      "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 Types

Contact Types Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to phone
label	string	False	The label which the contacts will be associated with
creation_date	date-time	Yes	The creation date of the record

List All Contact Types

curl -X GET \
https://api.closum.com/api/contact-type \
-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": "My Sample Contact Type",
                  "creation_date": "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 contact types created by your company.

HTTP Request

GET https://api.closum.com/api/contact-type

Create a Contact Type

curl -X POST \
curl -X POST \
https://api.closum.com/api/contact-type \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
      "label": "My Sample Contact Type"
}'

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

This endpoint allows you to add a new Contact Type.

HTTP Request

POST https://api.closum.com/api/contact-type

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
label	The label which the contacts will be associated with

Retrieve a Contact Type

curl -X GET \
https://api.closum.com/api/contact-type/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,
            "label": "My Sample Contact Type",
            "date_add": "2018-01-01T10:00:00+00:00"
      }
}

This endpoint retrieves a specific Contact Type.

HTTP Request

GET https://api.closum.com/api/contact-type/<ID>

URL Parameters

Parameter	Description
ID	The ID of Contact Type to retrieve

Update a Contact Type

curl -X PUT \
https://api.closum.com/api/contact-type/1 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer your.bearer.token' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json' \
-d '{
      "label": "My Sample Contact Type (Updated)"
}'

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

This endpoint updates a specific Contact Type.

HTTP Request

PUT https://api.closum.com/api/contact-type/<ID>

URL Parameters

Parameter	Description
ID	The ID of Contact Type to update

Request body

Body should be formated in (absolutely) correct JSON format

Parameter	Description
label	The label which the contacts will be associated with

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

Unqualified Lead Opt In

Unqualified Lead Opt In Properties

Parameter	Type	Read Only	Description
ID	integer	True	The id relative to unqualified lead opt in
unqualified_lead_id	integer	True	The lead_id which the unqualified 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.