API V2 Tracksale

The new version of the API integration of Tracksale was created with the purpose of that information had to be certified to be accessed. Among the differences between version 1.0 and 2.0:
  • Now a TOKEN is generated through our platform, or a request. In this way, we automate the whole process and also homologate access to information.
  • The API 2.0 includes the 1.0 version of the functions of live and RESTful API into a single API with various methods.
  • The new API works with RESTful model with JSON.

In this documentation you will also find examples of codes in the language of your choice, which can be changed at any time on the top right button.

Using the API requires the use of a key that we call TOKEN. It will be responsible for authenticating access to the system.

  1. For this, do the login in Tracksale with an administrator account.
  2. Access the menu Apps in the upper right corner next to the user name.


  3. Click Install in app

    "API V2".
  4. Clicking on NEW TOKEN.

  5. A new token will be generated.

  6. A new TOKEN will be generated and added to the list. New additions do not disable previous ones.

All API communication is made from the base URL api.tracksale.co/v2.

We will use TOKEN that we get in the header (without the need for conversion to base64), to authenticate access. As follows:

  • Key Authorization
  • Value bearer TOKEN

Where:

  • Authorization is the word Authorization
  • bearer is the word bearer and TOKEN is the TOKEN acquired here.

Campaign List



To list the campaigns we will use the following configuration


  • The method used will be: GET
  • The URL used will be: api.tracksale.co/v2/campaign

This method is responsible for listing ALL the campaigns, their codes and some details, such as the questions used.

It is possible to return only a specific campaign, it is possible using

  • URL: api.tracksale.co/v2/campaign/Campaign_code

Where Campaign_code is the code from the campaign you want to get information about.

To get the code for a specific campaign, you should first list all campaigns and get the "code" attribute of the return.



Return exemple:

{
            "name":"Customers_name",
            "code" : Campaign_code,
            "description" : Campaign_description,
            "detractors" : Detractors_name,
            "passives" : Neutrals_name,
            "promoters" : Promoters_name,
            "dispatches" : Dispatches_number,
            "comments" : Comments,
            "answers" : Answers,
            "main_channel" : "Main_channel",
            "create_time" : "Time_of_creation",
            "questions" : [
                {
                    "type" : "Question_type",
                    "title" : "Question_title",
                    "question" : "Question",
                    "secondary" : "Secondary_question"
                }
            ]

}

                                        

Code samples: Campaigns list

Type cURL

curl -X GET \
  https://api.tracksale.co/v2/campaign \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache'

Sendings



The sendings can be performed in two different ways

Scheduled dispatch:

  • The method used will be : POST
  • The URL used will be : api.tracksale.co/v2/campaign/Campaign_code/dispatch

    Where Campaign_code is the campaign code you want to send to.

The existence of the variable schedule_time is optional.

So we have two options

  • Insert variable "schedule_time":

  • This way you can use "schedule_time" to define when that sending will be performed, being defined as a "Uinx Timestamp" format in seconds. The body will look like this

    The following example shows the insertion with all variables, but there are cases where indentification, phone, and email variables can be omitted.

    Ex: If the campaign is trough SMS, it is not necessary to send the email, but it can still be sent. In campaigns via email the phone variable does not need to be sent, but if necessary, it is possible to send it.

    Sending both variables is indicated if you use campaign flow.

    Sending identification is recommended if you want to identify the customer by the same parameter of your company / platform

    {
        "customers": [
            {
                "name":"Customers_name",
                "email":"Customers_email",
                "identification": null,
                "phone": "Customers_phone",
                "tags" : [
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    },
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    }
                ]
            }
        ],
        "schedule_time": Timestamp_in_seconds
    }
    
                                            

    Application/json type

  • Do not insert the variable "schedule_time" :

  • This way should be used if your intention is to gather multiple sendings to a campaign, to do them at once at a later time. In this way, a batch code will be returned batchs, this code should be used in theBatch sendings.


    {
        "customers": [
            {
                "name":"Customers_name",
                "email":"Customers_email",
                "tags" : [
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    },
                    {
                        "name" : "TagExample",
                        "value" : "TagExample"
                    }
                ]
            }
        ],
    }
    
                                            

    Application/json type

    All subsequent sedings in the same campaign will return the same sedings batch until you send that batch.





Parameters

Attributes Types Required Description
name String No Client name
email String Yes (for email sendings) Customer Email
phone String Yes (for SMS sendings) Customer phone
tags Array No Tag name
tags Type Required Description
name String Yes Tag name
value String Yes Tag Value



Return example:

Without schedule_time
{
    "msg":"Customers have been successfully added!",
    "dispatch_code":"Dispatch_code",
    "status": {
        "duplicated":Number_of_duplications,
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions
    },
    "campaign": {
        "name":Campaign_name,
        "cod":Campaign_code
    }
}
 


With schedule_time
{
    "msg":"Dispatch executed!",
    "dispatch_code":"Dispatch_code",
    "status": {
        "duplicated":Number_of_duplications,
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions
    },
    "campaign": {
        "name":Campaign_name,
        "cod":Campaign_code
    }
}

                            

You can also return an array with customers that were not entered, either because they were duplicates or because they were invalid.

To do this, you must pass the parameter getNotInserted with the value 1. So we will return as follows.

{
    "msg":"Dispatch executed!",
    "dispatch_code":"Dispatch_code",
    "status": {
        "duplicated":Number_of_duplications,
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions
    },
    "campaign": {
        "name":Campaign_name,
        "cod":Campaign_code
    }
    "duplicated_customers": [
                {
                    "name":"customer name",
                    "email":"email@email.com"
                }
    ],
    "invalid_customers": [
                {
                    "name":"customer name",
                    "reason":"Invalid or empty main channel"
                }
    ],
}

                            

Type cURL

curl -X POST \
  https://api.tracksale.co/v2/campaign/campaign_code/dispatch \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "customers": [
        {
            "name":"Customers_name",
            "email":"Customers_email",
            "tags" : [
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                },
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                }
            ]
        }
    ],
    "schedule_time": Timestamp_in_Seconds
}'


Sending batch:

This batch should be sent using the following client Email settings

  • The method used will be: POST

  • The URL used will be: api.tracksale.co/v2/campaign/Campaign_code/dispatch/Codigo_lote


The body must be filled with the time the submission should be done in seconds, in the timestamp format.
As in the example:

{
    "time": Timestamp_in_seconds
}


Nome Type Required Description
time Integer Yes Time the send will be made, in seconds in the format timestamp. Use 0 to make an instant send


Return example:

{
    "msg":"Dispatch executed!",
    "customers":"Number_of_customers",
}

                            

Code samples : Batch sendings:

Type cURL

curl -X POST \
  https://api.tracksale.co/v2/campaign/campaign_code/dispatch/Codigo_lote \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "time": Timestamp_in_Seconds
}'

Insert Answers

We also provide a method of inserting responses. This method can be used with the following parameters.
  • The method will be:POST
  • The URL to use should be: api.tracksale.co/v2/answer
  • The body must be filled with the response batch using the following pattern
{
    "campaign_code": "Campaign_code",
    "answers":[
        {
            "name":"Customers_name",
            "email":"Customers_email",
            "score":Customer_score,
            "justification":""Customers_comment"",
            "create_time":Timestamp_in_seconds,
            "tags" : [
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                }
            ]
        }
    ]
}

                            
Parameters

Parameter Type Required Description
campaign_code String Yes Target Campaign Key. Obtained by method List Campaign
answers Array Yes List of answers

answers Type Required Description
name String Yes Costumer name
email String Yes, if sending was done by email Customer Email
phone String Yes, if sending was done by phone Client phone
score Integer Yes Score of the customer (between 0 to 10)
justification String No Customer review
create_time Integer No Date/hour of the answer in timestamp format (in seconds)
tags Array No Tags to add additional information to the client

tags Type Required Description
name String Yes Tag name
value String Yes Tag Value


Return example:

{
    "msg":"Number_of_answers Answer inserted"
    "status": {
        "invalid":Number_of_invalids,
        "inserted":Number_of_insertions,

    }
}

                            

Code samples : Insert answers

Type cURL

curl -X POST \
  https://api.tracksale.co/v2/answer \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "campaign_code": "campaign_code",
    "answers":[
        {
            "name":"customers_name",
            "email":"customers_Email",
            "score":Customer_score,
            "justification":"customers_comment",
            "create_time":Timestamp_in_seconds,
            "tags" : [
                {
                    "name" : "TagExample",
                    "value" : "TagExample"
                }
            ]
        }
    ]
}'

Reports is our method for reporting, it's responsible for showing details of all your campaigns or a campaign.

All API communication is made from the base URL api.tracksale.co/v2/report/DETAILS.

Where DETAILS should be replaced by the details you wish to obtain through the requisition

The method to be used will be the GET

    The header must be filled with the parameters where
  • Key Authorization
  • Value bearer TOKEN

Comments

The method to be used must be :GET

The URL to use should be :api.tracksale.co/v2/report/answer

Method responsible for returning customer comments.


Parameters

Parameter Type Default Required Description
start Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Initial date in yyyy-mm-dd format
end Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Final date in the format yyyy-mm-dd
limit Integer By default it will show 10 comments per request. No Total comments to be returned. Use -1 to return all.
tags Boolean By default this is false, meaning no tags will be displayed. No Returns the tags related to the answers
justifReturn String By default we will show the format "level" No

Return format of justifications.


"array" -

Returns all in a single array.


"level" -

Returns JSON format with subfolders of grouped justifications.

codes String By default it will show comments for all campaigns No Used to show comments for a specific campaign, or comments for all campaigns. You can also show comments for more than one campaign at a time by using the comma as a separator (Ex: codes=52,51,50 will show the comments of the campaigns whose Campaign_code is 50, 51 e 52)


Return example:

[
    {
        "time": 1454340407,
        "type": "Email",
        "name": "Customers_name",
        "email": "Customers_email",
        "identification": null,
        "phone": "Customers_phone",
        "alternative_email": "Customers_email",
        "alternative_phone": "Customers_phone",
        "nps_answer": Score,
        "last_nps_answer": Score,
        "nps_comment": Comment,
        "campaign_name": "Campaign_name",
        "campaign_code": "Campaign_code",
        "id": 6805511,
        "deadline": null,
        "elapsed_time": 17,
        "dispatch_time": null,
        "reminder_time": null,
        "status": "Status",
        "priority": "None",
        "assignee": "Assignee_name",
        "picture": null,
        "tags": [],
        "categories": [],
        "justifications": []
    }
]

                            

Dispatch

The method to be used must be :GET

The URL to use should be: api.tracksale.co/v2/report/dispatch

Method responsible for returning the batchs and their data, such as inserted customers, the time it was performed, its status and the clients that were inserted into it.

[
    {
        "campaign": {
            "name": "Camapaign_name",
            "code": "Campaign_code"
        },
        "dispatch_code": "Code_of_dispatch",
        "status": Status_of_dispatch,
        "create_time": "Campaign_creation_time",
        "customers": [
            {
                "name": "Customers_name",
                "identification": null,
                "email": "Customers_email",
                "phone": "Customers_phone",
                "dispatch_time": "Code_of_dispatch",
                "status": "Status_of_dispatch"
            }
        ]
    }
]

                            
Parameters

Parameter Type Default Required Description
start Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Initial date in yyyy-mm-dd format
end Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Final date in the format yyyy-mm-dd
codes String By default it will show comments for all campaigns No Used to show comments for a specific campaign, or comments for all campaigns. You can also show comments for more than one campaign at a time by using the comma as a separator. (Ex: codes=52,51,50 will show the comments of the campaigns whose Campaign_code is 50, 51 e 52)


NPS

The method to be used must be : GET

The URL to use should be:api.tracksale.co/v2/report/nps

Method responsible for returning the number of submissions, the numbers of detractors, promoters and neutrals and their respective percentages and also the value of nps.

Parameters

Parameter Type Default Required Description
start Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Initial date in yyyy-mm-dd format
end Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Final date in the format yyyy-mm-dd
compare Boolean By default is false No Returns the NPS data for the previous date filter period.
codes String By default it will show comments for all campaigns No Used to show comments for a specific campaign, or comments for all campaigns. You can also show comments for more than one campaign at a time by using the comma as a separator (Ex: codes=52,51,50 will show the comments of the campaigns whose Campaign_code is 50, 51 e 52)


Return example:

{
    "dispatches": Number_of_dispatches,
    "promoters": Number_of_promoter,
    "detractors": Number_of_detractors,
    "passives": Number_of_neutrals,
    "detractors_percentage": Percentage_of_detractors,
    "passives_percentage": Percentage_of_neutrals,
    "promoters_percentage": Percentage_of_promoters,
    "nps": Period_NPS,
    "compare": {
        "dispatches": Number_of_dispatches,
        "promoters": Number_of_promoter,
        "detractors": Number_of_detractors,
        "passives": Number_of_neutrals,
        "detractors_percentage": Percentage_of_detractors,
        "passives_percentage": Percentage_of_neutrals,
        "promoters_percentage": Percentage_of_promoters,
        "nps": Period_NPS,
    }
}

                            

Categories

The method to be used must be :GET

The URL to use should be: api.tracksale.co/v2/report/category

Method responsible for returning campaign categories according to NPS.

Parameters

Parameter Type Default Required Description
start Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Initial date in yyyy-mm-dd format
end Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Final date in the format yyyy-mm-dd
codes String By default it will show comments for all campaigns No Used to show comments for a specific campaign, or comments for all campaigns. You can also show comments for more than one campaign at a time by using the comma as a separator. (Ex: codes=52,51,50 will show the comments of the campaigns whose Campaign_code is 50, 51 e 52)


Return example:

[
    {
        "id": 6805511,
        "name": "Product",
        "color": "#F8D347",
        "total": 25,
        "nps": Period_NPS,
        "total": total,

    }
]

                            

Get campaign status

The method to be used must be :GET

The URL to use should be: api.tracksale.co/v2/report/status

Method responsible for returning campaign statuses.



Parameters

Parameter Type Default Required Description
start Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Initial date in yyyy-mm-dd format
end Date By default we will show results 30 days prior to the date of the request
(Ex: If you are sending this request on 01/31/2017 and do not include the initial and final interval you want to do your search, the returned period will be from 01/01/2017 to 01/31/2017)
No Final date in the format yyyy-mm-dd
codes String By default it will show comments for all campaigns No Used to show comments for a specific campaign, or comments for all campaigns. You can also show comments for more than one campaign at a time by using the comma as a separator. (Ex: codes=52,51,50 will show the comments of the campaigns whose Campaign_code is 50, 51 e 52)


Return exemple:

[
    {
        "id": 76,
        "name": "Pendente Cliente",
        "total": 25,
        "color": "#F8D347"
    }
]

                            

Code samples : Reports /DETAILS

Type cURL

curl -X GET \
  'https://api.tracksale.co/v2/report/DETALHES?start=DATA_INICIO&end=DATA_FIM' \
  -H 'authorization: bearer TOKEN' \
  -H 'cache-control: no-cache'