Get started

Authentication

Nicereply uses Basic HTTP Authentication to allow access to the API. You can leave username blank, and use private key as a password.

API expects for the API key to be included in all API requests to the server.

Request format

We recommend you to put Accept header which should contain application/json value because this is the only format we are supporting now.
And we also recommend you for each POST and PATCH request put Content-Type header with application/json value because we are receiving data in JSON format from your applications.

Accept: application/json
Content-Type: application/json

Pagination

{
  "_results": [
    // ...
  ],
  "_pagination": {
    "total": 62,
    "count": 10,
    "per_page": 10,
    "current_page": 2,
    "total_pages": 7,
    "links": {
      "next": "/v1/endpoint?page=3",
      "previous": "/v1/endpoint?page=1"
    }
  }
}

Pagination is available in every endpoint which return collection of the resources. Information about pagination is in _pagination field with this subfields:

Field	Type	Description
total	integer	Count of all resources
count	integer	Count of resources in current page
per_page	integer	Limit how many resources can be in one page
current_page	integer	Current page
total_pages	integer	Total pages
links	object	Paths to next & previous page

links object

Field	Type	Description
next	string (optional)	Path to next page. When there is no next page, field is not presented.
previous	string (optional)	Path to previous page. When there is no previous page, field is not presented.

Pagination query parameters

Field	Type	Default	Description
page	integer (optional)	1	Requested page
per_page	integer (optional)	10	How many recources will be in response per page. (10 - 100).

Date format

In all API endpoints (in responses and in query parameters) we use date/time format ISO 8601.

These three formats are valid on our side:
2017-10-24T13:37:00+02:00
2017-10-24T13:37:00-02:00
2017-10-24T13:37:00Z

Errors

{
  "errors": [
    "Validation error in queryParameters[per_page]: This value should be 100 or less.",
    "Validation error in queryParameters[page]: This value should be a valid number.",
    "Validation error in requestBody[survey_id]: This field is missing."
  ]
}

When occurs an error, there will be response with errors field as array that contains all errors with corresponding HTTP status code.

HTTP Status Code	Description
400 Bad Request	Validation error, wrong JSON syntax, ...
401 Unauthorized	Wrong or missing basic authentication.
402 Payment Required	Trial ended or service wasn't paid.
404 Not Found	Resource or route cannot be found.
429 Too Many Requests	When rate limits was hitted (currently no limits).

New IDs

As we announced earlier, on August 1, 2023, we upgraded our incremental numeric IDs to universally unique identifiers (UUIDs). Here is our plan:

• ✅ Step 1: We have added uuid fields to responses and are now accepting UUIDs in requests.
• ✅ Step 2: After August 1, 2023, we will no longer support numerical IDs. At this point, we will remove the uuid field, and the id field will only contain UUIDs.
• ℹ️ Although we have removed numerical IDs from our responses, we will continue to support endpoints with numerical IDs as ID parameters for a short time.

Please refer to our documentation for more information on each individual endpoint.

Ratings

Rating model fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	string	No	Min: 0, Max: 10
from	string	No
status	string(enum)	no	Valid values: open - rating is editable by customer closed - rating is processed and can't be edited
ip_address	integer	No	IPv4 format
comment	string	Yes
survey	object	No
user	object	No
customer	object	Yes
ticket	object	Yes
extra_questions	array	Yes	Array of extra_question objects.
created_at	string	No	ISO8601 date
updated_at	string	No	ISO8601 date

survey object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
metric	string(enum)	No	Valid values: CSAT, CES, NPS

user object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
username	string	No

customer object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...

ticket object fields

Field	Type	Nullable	Description
value	string	No
link	string	Yes	Direct URL to the ticket (only if the integration supports this feature).

extra_question object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	integer	No

Create new rating

Response 201 Created

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": null,
    "survey": {
      "id": "df05e734-aed3-4da1-9fcb-730a2415698e",
      "type": "CSAT"
    },
    "customer": null,
    "user": null,
    "extra_questions": [
      {
        "id": "a8febabb-f6f1-4fce-950a-da18da8b5e6d",
        "score": 5
      }
    ]
  }
}

This endpoint creates new rating and return it to the response with HTTP status 201 Created.

HTTP Request

POST https://api.nicereply.com/v1/ratings

BODY Parameters

Parameter	Required	Nullable	Type	Description
survey_id	Yes	No	string(UUID)	NPS Survey ID
score	Yes	No	integer	Min: 0, Max: 10; it depends on the metric and rating scale of survey.
from	No*	No	string	From is required when Name field is enabled in the survey.
comment	No	No	string	Rating comment
ticket	No	Yes	string	Ticket Number
user	Yes	No	object	Object must contain only one of the following fields: id (string(UUID)) OR username (string).
customer_id	No	Yes	string(UUID)	Customer ID
ip_address	No	No	string	IP address of the rating (currently is only IPv4 supported)
extra_questions	No*	Yes	array	Array of extra_question objects.

extra_question object parameters

Parameter	Required	Nullable	Type	Description
id	Yes	No	string(UUID)	Extra question ID
score	Yes	No	integer	Min: 1, Max: 10

CSAT

CSAT Rating model fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	string	No	Min: 1, Max: 10
from	string	No
ip_address	integer	No	IPv4 format
comment	string	Yes
created_at	string	No	ISO8601 date
updated_at	string	No	ISO8601 date
survey	object	No
user	object	No
customer	object	Yes
ticket	object	Yes
extra_questions	array	Yes	Array of extra_question objects
status	string(enum)	no	Valid values: open - rating is editable by customer closed - rating is processed and can't be edited

survey object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
metric	string(enum)	No	Valid values: CSAT

user object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
username	string	No

customer object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...

ticket object fields

Field	Type	Nullable	Description
value	string	No
link	string	Yes	Direct URL to the ticket (only if the integration supports this feature).

extra_question object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	integer	No

Get all CSAT ratings

Response 200 OK

{
  "_results": [
    {
      "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "ticket": {
        "value": "cnv_2841049",
        "link": null
      },
      "survey": {
        "id": "510268e5-c708-415b-953e-64f06a017145",
        "type": "CSAT"
      },
      "customer": {
        "id": "1c8a0177-5d67-48fc-baaa-691567404cdb"
      },
      "user": {
        "id": "c674b3b4-265f-4fcc-bca2-f2df99127a20",
        "username": "mr-unclebob"
      }, 
      "status": "open",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "score": 1
        }
      ],
      "_links": {
        "self": "/v1/csat/ratings/904e0950-959b-4a90-93ad-4fdc62a4a14c",
        "survey": "/v1/surveys/510268e5-c708-415b-953e-64f06a017145",
        "user": "/v1/users/c674b3b4-265f-4fcc-bca2-f2df99127a20",
        "customer": "/v1/customers/1c8a0177-5d67-48fc-baaa-691567404cdb"
      }
    }

    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all ratings which belongs to CSAT metric.
Sorting is performed by created_at field.

HTTP Request

GET https://api.nicereply.com/v1/csat/ratings

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get CSAT rating

Response 200 OK

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": {
      "value": "cnv_2841049",
      "link": null
    },
    "survey": {
      "id": "510268e5-c708-415b-953e-64f06a017145",
      "type": "CSAT"
    },
    "customer": {
      "id": "1c8a0177-5d67-48fc-baaa-691567404cdb"
    },
    "user": {
      "id": "c674b3b4-265f-4fcc-bca2-f2df99127a20",
      "username": "mr-unclebob"
    },
    "status": "open",
    "extra_questions": [
      {
        "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
        "score": 1
      }
    ],
    "_links": {
      "self": "/v1/csat/ratings/904e0950-959b-4a90-93ad-4fdc62a4a14c",
      "survey": "/v1/surveys/510268e5-c708-415b-953e-64f06a017145",
      "user": "/v1/users/c674b3b4-265f-4fcc-bca2-f2df99127a20",
      "customer": "/v1/customers/1c8a0177-5d67-48fc-baaa-691567404cdb"
    }
  }
}

This endpoint retrieves a specific CSAT rating.

HTTP Request

GET https://api.nicereply.com/v1/csat/ratings/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the CSAT rating to retrieve. More about IDs...

Get CSAT stats

Response 200 OK

{
  "_results": {
    "average": 0,
    "count": 0
  }
}

This endpoint retrieves CSAT metric stats.

HTTP Request

GET https://api.nicereply.com/v1/csat/stats

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get CSAT histogram

Response 200 OK

{
  "_results": {
    "histogram": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "7": 0,
      "8": 0,
      "9": 0,
      "10": 0
    }
  }
}

This endpoint retrieves metric histogram for CSAT metric.

HTTP Request

GET https://api.nicereply.com/v1/csat/histogram

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get CSAT surveys

Response 200 OK

{
  "_results": [
    {
      "id": "9e3722f9-1855-4188-80d2-9ab918d8c43f",
      "name": "Helpdesk Survey",
      "metric": "CSAT",
      "scale": "CSAT3",
      "distribution": "trigger",
      "rating_scale": "faces",
      "question": "How nice was my reply?",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "label": "Some extra question is the survey",
          "rating_scale": "thumbs",
          "scale": "CSAT2",
          "required": true
        }
      ],
      "_links": {
        "self": "/v1/surveys/9e3722f9-1855-4188-80d2-9ab918d8c43f"
      }
    }
  ],
  "_pagination": {
    "total": 1,
    "count": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all surveys which belongs to CSAT metric.

HTTP Request

GET https://api.nicereply.com/v1/csat/surveys

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Create CSAT new rating

Response 201 Created

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": null,
    "survey": {
      "id": "df05e734-aed3-4da1-9fcb-730a2415698e",
      "type": "CSAT"
    },
    "customer": null,
    "user": null
  }
}

This endpoint creates new rating and return it to the response with HTTP status 201 Created.

HTTP Request

POST https://api.nicereply.com/v1/csat/ratings

BODY Parameters

Parameter	Required	Nullable	Type	Description
survey_id	Yes	No	string(UUID)	CSAT Survey ID
score	Yes	No	integer	Min: 1, Max: 10; it depends on rating scale of survey.
from	No*	No	string	From is required when Name field is enabled in the survey.
comment	No	No	string	Rating comment
ticket	No	Yes	string	Ticket Number
user	Yes	No	object	Object must contain only one of the following fields: id (string(UUID)) OR username (string).
customer_id	No	Yes	string(UUID)	Customer ID
ip_address	No	No	string	IP address of the rating (currently is only IPv4 supported)
extra_questions	No*	No	array	Array of extra_question objects.

extra_question object parameters

Parameter	Required	Nullable	Type	Description
id	Yes	No	string(UUID)	Extra question ID
score	Yes	No	integer	Min: 1, Max: 10

CES

CES Rating model fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	string	No	Min: 1, Max: 7
from	string	No
ip_address	integer	No	IPv4 format
comment	string	Yes
created_at	string	No	ISO8601 date
updated_at	string	No	ISO8601 date
survey	object	No
user	object	No
customer	object	Yes
ticket	object	Yes
extra_questions	array	Yes	Array of extra_question objects
status	string(enum)	no	Valid values: open - rating is editable by customer closed - rating is processed and can't be edited

survey object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
metric	string(enum)	No	Valid values: CES

user object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
username	string	No

customer object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...

ticket object fields

Field	Type	Nullable	Description
value	string	No
link	string	Yes	Direct URL to the ticket (only if the integration supports this feature).

extra_question object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	integer	No

Get all CES ratings

Response 200 OK

{
  "_results": [
    {
      "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "ticket": {
        "value": "cnv_2841049",
        "link": null
      },
      "survey": {
        "id": "510268e5-c708-415b-953e-64f06a017145",
        "type": "CES"
      },
      "customer": {
        "id": "1c8a0177-5d67-48fc-baaa-691567404cdb"
      },
      "user": {
        "id": "c674b3b4-265f-4fcc-bca2-f2df99127a20",
        "username": "mr-unclebob"
      },
      "status": "open",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "score": 1
        }
      ],
      "_links": {
        "self": "/v1/csat/ratings/904e0950-959b-4a90-93ad-4fdc62a4a14c",
        "survey": "/v1/surveys/510268e5-c708-415b-953e-64f06a017145",
        "user": "/v1/users/c674b3b4-265f-4fcc-bca2-f2df99127a20",
        "customer": "/v1/customers/1c8a0177-5d67-48fc-baaa-691567404cdb"
      }
    }

    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all ratings which belongs to CES metric.
Sorting is performed by created_at field.

HTTP Request

GET https://api.nicereply.com/v1/ces/ratings

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get CES rating

Response 200 OK

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": {
      "value": "cnv_2841049",
      "link": null
    },
    "survey": {
      "id": "510268e5-c708-415b-953e-64f06a017145",
      "type": "CES"
    },
    "customer": {
      "id": "1c8a0177-5d67-48fc-baaa-691567404cdb"
    },
    "user": {
      "id": "c674b3b4-265f-4fcc-bca2-f2df99127a20",
      "username": "mr-unclebob"
    },
    "status": "open",
    "extra_questions": [
      {
        "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
        "score": 1
      }
    ],
    "_links": {
      "self": "/v1/csat/ratings/904e0950-959b-4a90-93ad-4fdc62a4a14c",
      "survey": "/v1/surveys/510268e5-c708-415b-953e-64f06a017145",
      "user": "/v1/users/c674b3b4-265f-4fcc-bca2-f2df99127a20",
      "customer": "/v1/customers/1c8a0177-5d67-48fc-baaa-691567404cdb"
    }
  }
}

This endpoint retrieves a specific CES rating.

HTTP Request

GET https://api.nicereply.com/v1/ces/ratings/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the CES rating to retrieve. More about IDs...

Get CES stats

Response 200 OK

{
  "_results": {
    "average": 0,
    "count": 0
  }
}

This endpoint retrieves CES metric stats.

HTTP Request

GET https://api.nicereply.com/v1/ces/stats

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get CES histogram

Response 200 OK

{
  "_results": {
    "histogram": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "7": 0
    }
  }
}

This endpoint retrieves metric histogram for CES metric.

HTTP Request

GET https://api.nicereply.com/v1/ces/histogram

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get CES surveys

Response 200 OK

{
  "_results": [
    {
      "id": "9e3722f9-1855-4188-80d2-9ab918d8c43f",
      "name": "CES Survey",
      "metric": "CES",
      "scale": "CES",
      "distribution": "template",
      "rating_scale": "ces",
      "question": "Nicereply made it easy for me to handle my issue.",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "label": "Some extra question is the survey",
          "rating_scale": "thumbs",
          "scale": "CSAT2",
          "required": true
        }
      ],
      "_links": {
        "self": "/v1/surveys/9e3722f9-1855-4188-80d2-9ab918d8c43f"
      }
    }
  ],
  "_pagination": {
    "total": 1,
    "count": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all surveys which belongs to CES metric.

HTTP Request

GET https://api.nicereply.com/v1/ces/surveys

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Create new CES rating

Response 201 Created

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": null,
    "survey": {
      "id": "df05e734-aed3-4da1-9fcb-730a2415698e",
      "type": "CES"
    },
    "customer": null,
    "user": null
  }
}

This endpoint creates new rating and return it to the response with HTTP status 201 Created.

HTTP Request

POST https://api.nicereply.com/v1/ces/ratings

BODY Parameters

Parameter	Required	Nullable	Type	Description
survey_id	Yes	No	string(UUID)	CSAT Survey ID
score	Yes	No	integer	Min: 1, Max: 7
from	No*	No	string	From is required when Name field is enabled in the survey.
comment	No	No	string	Rating comment
ticket	No	Yes	string	Ticket Number
user	Yes	No	object	Object must contain only one of the following fields: id (string(UUID)) OR username (string).
customer_id	No	Yes	string(UUID)	Customer ID
ip_address	No	No	string	IP address of the rating (currently is only IPv4 supported)

extra_question object parameters

Parameter	Required	Nullable	Type	Description
id	Yes	No	string(UUID)	Extra question ID
score	Yes	No	integer	Min: 1, Max: 10

NPS

NPS Rating model fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	string	No	Min: 0, Max: 10
from	string	No
ip_address	integer	No	IPv4 format
comment	string	Yes
created_at	string	No	ISO8601 date
updated_at	string	No	ISO8601 date
survey	object	No
user	object	No
customer	object	Yes
ticket	object	Yes
extra_questions	array	Yes	Array of extra_question objects
status	string(enum)	no	Valid values: open - rating is editable by customer closed - rating is processed and can't be edited

survey object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
metric	string(enum)	No	Valid values: NPS

user object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
username	string	No

customer object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...

ticket object fields

Field	Type	Nullable	Description
value	string	No
link	string	Yes	Direct URL to the ticket (only if the integration supports this feature).

extra_question object fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
score	integer	No

Get all NPS ratings

Response 200 OK

{
  "_results": [
    {
      "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "ticket": {
        "value": "cnv_2841049",
        "link": null
      },
      "survey": {
        "id": "510268e5-c708-415b-953e-64f06a017145",
        "type": "NPS"
      },
      "customer": {
        "id": "1c8a0177-5d67-48fc-baaa-691567404cdb"
      },
      "user": {
        "id": "c674b3b4-265f-4fcc-bca2-f2df99127a20",
        "username": "mr-unclebob"
      },
      "status": "open",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "score": 1
        }
      ],
      "_links": {
        "self": "/v1/csat/ratings/904e0950-959b-4a90-93ad-4fdc62a4a14c",
        "survey": "/v1/surveys/510268e5-c708-415b-953e-64f06a017145",
        "user": "/v1/users/c674b3b4-265f-4fcc-bca2-f2df99127a20",
        "customer": "/v1/customers/1c8a0177-5d67-48fc-baaa-691567404cdb"
      }
    }

    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all ratings which belongs to NPS metric.
Sorting is performed by created_at field.

HTTP Request

GET https://api.nicereply.com/v1/nps/ratings

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get NPS rating

Response 200 OK

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": {
      "value": "cnv_2841049",
      "link": null
    },
    "survey": {
      "id": "510268e5-c708-415b-953e-64f06a017145",
      "type": "NPS"
    },
    "customer": {
      "id": "1c8a0177-5d67-48fc-baaa-691567404cdb"
    },
    "user": {
      "id": "c674b3b4-265f-4fcc-bca2-f2df99127a20",
      "username": "mr-unclebob"
    },
    "status": "open",
    "extra_questions": [
      {
        "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
        "score": 1
      }
    ],
    "_links": {
      "self": "/v1/csat/ratings/904e0950-959b-4a90-93ad-4fdc62a4a14c",
      "survey": "/v1/surveys/510268e5-c708-415b-953e-64f06a017145",
      "user": "/v1/users/c674b3b4-265f-4fcc-bca2-f2df99127a20",
      "customer": "/v1/customers/1c8a0177-5d67-48fc-baaa-691567404cdb"
    }
  }
}

This endpoint retrieves a specific NPS rating.

HTTP Request

GET https://api.nicereply.com/v1/nps/ratings/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the NPS rating to retrieve. More about IDs...

Get NPS stats

Response 200 OK

{
  "_results": {
    "nps_score": 0,
    "count": 0,
    "groups": {
      "promoters": 0,
      "passives": 0,
      "detractors": 0
    }
  }
}

This endpoint retrieves NPS metric stats.

HTTP Request

GET https://api.nicereply.com/v1/nps/stats

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get NPS histogram

Response 200 OK

{
  "_results": {
    "histogram": {
      "0": 0,
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "7": 0,
      "8": 0,
      "9": 0,
      "10": 0
    }
  }
}

This endpoint retrieves metric histogram for NPS metric.

HTTP Request

GET https://api.nicereply.com/v1/nps/histogram

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get NPS surveys

Response 200 OK

{
  "_results": [
    {
      "id": "f1975e46-0209-44bc-b145-c1e64b0f8624",
      "name": "Customer Feedback Survey",
      "metric": "NPS",
      "scale": "NPS",
      "distribution": "template",
      "rating_scale": "nps",
      "question": "How likely is it that you would recommend Nicereply to a friend or colleague?",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "label": "Some extra question is the survey",
          "rating_scale": "thumbs",
          "scale": "CSAT2",
          "required": true
        }
      ],
      "_links": {
        "self": "/v1/surveys/f1975e46-0209-44bc-b145-c1e64b0f8624"
      }
    }
  ],
  "_pagination": {
    "total": 1,
    "count": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all surveys which belongs to NPS metric.

HTTP Request

GET https://api.nicereply.com/v1/nps/surveys

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Create new NPS rating

Response 201 Created

{
  "_results": {
    "id": "904e0950-959b-4a90-93ad-4fdc62a4a14c",
    "score": 5,
    "from": "Viktor Magic",
    "ip_address": "8.8.8.8",
    "comment": "Nice reply! :)",
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "ticket": null,
    "survey": {
      "id": "df05e734-aed3-4da1-9fcb-730a2415698e",
      "type": "NPS"
    },
    "customer": null,
    "user": null
  }
}

This endpoint creates new rating and return it to the response with HTTP status 201 Created.

HTTP Request

POST https://api.nicereply.com/v1/nps/ratings

BODY Parameters

Parameter	Required	Nullable	Type	Description
survey_id	Yes	No	string(UUID)	NPS Survey ID
score	Yes	No	integer	Min: 0, Max: 10
from	No*	No	string	From is required when Name field is enabled in the survey.
comment	No	No	string	Rating comment
ticket	No	Yes	string	Ticket Number
user	Yes	No	object	Object must contain only one of the following fields: id (string(UUID)) OR username (string).
customer_id	No	Yes	string(UUID)	Customer ID
ip_address	No	No	string	IP address of the rating (currently is only IPv4 supported)
extra_questions	No*	No	array	Array of extra_question objects.

extra_question object parameters

Parameter	Required	Nullable	Type	Description
id	Yes	No	string(UUID)	Extra question ID
score	Yes	No	integer	Min: 1, Max: 10

Customers

Customer model fields

Field	Type	Nullable	Description
id	string(UUID)	No	More about new IDs...
name	string	No
email	string	No
tickets	integer	No
created_at	string	No	ISO8601 date
updated_at	string	No	ISO8601 date

Get all customers

Response 200 OK

{
  "_results": [
    {
      "id": "461b20eb-b6e9-43ed-bbd3-6c7131dded16",
      "name": "Freddy Coleman",
      "email": "freddy-coleman@example.com",
      "tickets": 4,
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "_links": {
        "self": "/v1/customers/32"
      }
    },
    {
      "id": "3571eea9-a559-4f41-8bf0-f8a3fc660550",
      "name": "Robert C. Martin",
      "email": "unclebob@example.com",
      "tickets": 38,
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "_links": {
        "self": "/v1/customers/16"
      }
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your customers.

HTTP Request

GET https://api.nicereply.com/v1/customers

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Get stats for all customers

Response 200 OK

{
  "_results": [
    {
      "id": "461b20eb-b6e9-43ed-bbd3-6c7131dded16",
      "stats": {
        "CSAT": {
          "average": 6.4444,
          "count": 153
        },
        "CES": {
          "average": 5,
          "count": 133
        },
        "NPS": {
          "nps_score": -71,
          "count": 17,
          "groups": {
            "promoters": 2,
            "passives": 1,
            "detractors": 14
          }
        }
      }
    },
    {
      "id": "3571eea9-a559-4f41-8bf0-f8a3fc660550",
      "stats": {
        "CSAT": {
          "average": 0,
          "count": 0
        },
        "CES": {
          "average": 0,
          "count": 0
        },
        "NPS": {
          "nps_score": 0,
          "count": 0,
          "groups": {
            "promoters": 0,
            "passives": 0,
            "detractors": 0
          }
        }
      }
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your customers with stats to all metrics.

HTTP Request

GET https://api.nicereply.com/v1/customers/stats

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a customer

Response 200 OK

{
  "_results": {
    "id": "461b20eb-b6e9-43ed-bbd3-6c7131dded16",
    "name": "Freddy Coleman",
    "email": "freddy-coleman@example.com",
    "tickets": 4,
    "created_at": "2017-10-24T13:37:01+02:00",
    "updated_at": "2017-10-24T13:37:01+02:00",
    "_links": {
      "self": "/v1/customers/461b20eb-b6e9-43ed-bbd3-6c7131dded16"
    }
  }
}

This endpoint retrieves a specific customer.

HTTP Request

GET https://api.nicereply.com/v1/customers/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the customer to retrieve. More about IDs...

Get a customer ratings

Response 200 OK

{
  "_results": [
    {
      "id": "3175bdda-8ab1-4e5a-8b29-ba6473739bfe",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "ticket": {
        "value": "19867463",
        "link": null
      },

      ...
    },

    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all ratings which belongs to the customer.

HTTP Request

GET https://api.nicereply.com/v1/customers/<ID>/ratings

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the customer to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a customer stats

Response 200 OK

{
  "_results": {
    "CSAT": {
      "average": 6.4444,
      "count": 153
    },
    "CES": {
      "average": 5,
      "count": 133
    },
    "NPS": {
      "nps_score": -71,
      "count": 17,
      "groups": {
        "promoters": 2,
        "passives": 1,
        "detractors": 14
      }
    }
  }
}

This endpoint retrieves customer stats for all metrics.

HTTP Request

GET https://api.nicereply.com/v1/customers/<ID>/stats

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the customer to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get a customer histogram

Response 200 OK

{
  "_results": {
    "CSAT": {
      "histogram": {
        "1": 3,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 99,
        "6": 0,
        "7": 0,
        "8": 11,
        "9": 0,
        "10": 40
      }
    },
    "CES": {
      "histogram": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 133,
        "6": 0,
        "7": 0
      }
    },
    "NPS": {
      "histogram": {
        "0": 0,
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 14,
        "6": 0,
        "7": 1,
        "8": 0,
        "9": 2,
        "10": 0
      }
    }
  }
}

This endpoint retrieves customer histogram for all metrics.

HTTP Request

GET https://api.nicereply.com/v1/customers/<ID>/histogram

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the customer to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Surveys

Survey model fields

Field	Type	Description
id	string(UUID)	More about new IDs...
name	string
metric	string(enum)	Valid values: CSAT, CES or NPS
scale	string(enum)	Valid values: CSAT10, CSAT5, CSAT3, CSAT2, CES or NPS
distribution	string(enum)	Valid values: template, trigger or campaign
rating_scale	string(enum)	Valid values: faces, stars, stars5, thumbs, ces or nps
question	string
extra_questions	array	Provided only when metric is CSAT!

extra_question object parameters

Parameter	Type	Description
id	string(UUID)	More about new IDs...
label	string
rating_scale	string(enum)	Valid values: faces, stars, stars5, thumbs, ces or nps
scale	string(enum)	Valid values: CSAT10, CSAT5, CSAT3, CSAT2, CES or NPS
required	boolean

Get all surveys

Response 200 OK

{
  "_results": [
    {
      "id": "9e3722f9-1855-4188-80d2-9ab918d8c43f",
      "name": "Helpdesk Survey",
      "metric": "CSAT",
      "scale": "CSAT3",
      "distribution": "trigger",
      "rating_scale": "faces",
      "question": "How nice was my reply?",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "label": "Some extra question is the survey",
          "rating_scale": "thumbs",
          "scale": "CSAT2",
          "required": true
        }
      ],
      "_links": {
        "self": "/v1/surveys/9e3722f9-1855-4188-80d2-9ab918d8c43f"
      }
    },
    {
      "id": "c2b7b871-1a3a-4837-bb91-d3b85a6e0fd1",
      "name": "CES Survey",
      "metric": "CES",
      "scale": "CES",
      "distribution": "template",
      "rating_scale": "ces",
      "question": "Nicereply made it easy for me to handle my issue.",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "label": "Some extra question is the survey",
          "rating_scale": "thumbs",
          "scale": "CSAT2",
          "required": true
        }
      ],
      "_links": {
        "self": "/v1/surveys/c2b7b871-1a3a-4837-bb91-d3b85a6e0fd1"
      }
    },
    {
      "id": "f1975e46-0209-44bc-b145-c1e64b0f8624",
      "name": "Customer Feedback Survey",
      "metric": "NPS",
      "scale": "NPS",
      "distribution": "template",
      "rating_scale": "nps",
      "question": "How likely is it that you would recommend Nicereply to a friend or colleague?",
      "extra_questions": [
        {
          "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
          "label": "Some extra question is the survey",
          "rating_scale": "thumbs",
          "scale": "CSAT2",
          "required": true
        }
      ],
      "_links": {
        "self": "/v1/surveys/f1975e46-0209-44bc-b145-c1e64b0f8624"
      }
    }
  ],
  "_pagination": {
    "total": 3,
    "count": 3,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your surveys.
Sorting is performed by created_at field.

HTTP Request

GET https://api.nicereply.com/v1/surveys

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Get stats for all surveys

Response 200 OK

{
  "_results": [
    {
      "id": "9e3722f9-1855-4188-80d2-9ab918d8c43f",
      "type": "CSAT",
      "stats": {
        "average": 0,
        "count": 0
      }
    },
    {
      "id": "c2b7b871-1a3a-4837-bb91-d3b85a6e0fd1",
      "type": "CES",
      "stats": {
        "average": 0,
        "count": 0
      }
    },
    {
      "id": "f1975e46-0209-44bc-b145-c1e64b0f8624",
      "type": "NPS",
      "stats": {
        "nps_score": 0,
        "count": 0,
        "groups": {
          "promoters": 0,
          "passives": 0,
          "detractors": 0
        }
      }
    }
  ],
  "_pagination": {
    "total": 3,
    "count": 3,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your surveys with stats.

HTTP Request

GET https://api.nicereply.com/v1/surveys/stats

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a survey

Response 200 OK

{
  "_results": {
    "id": "d6ef70ee-9a95-41ee-ba70-96b0f4d9e6e4",
    "name": "CES Survey",
    "metric": "CES",
    "scale": "CES",
    "distribution": "template",
    "rating_scale": "ces",
    "question": "Nicereply made it easy for me to handle my issue.",
    "extra_questions": [
      {
        "id": "76c88941-7d7e-45e8-95a6-1fe10b77dcfc",
        "label": "Some extra question is the survey",
        "rating_scale": "thumbs",
        "scale": "CSAT2",
        "required": true
      }
    ],
    "_links": {
      "self": "/v1/surveys/d6ef70ee-9a95-41ee-ba70-96b0f4d9e6e4"
    }
  }
}

This endpoint retrieves a specific survey.

HTTP Request

GET https://api.nicereply.com/v1/surveys/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the survey to retrieve. More about IDs...

Get a survey ratings

Response 200 OK

{
  "_results": [
    {
      "id": "0359f834-1909-4b59-bf35-f0c7428d2ee2",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "ticket": null,
      "survey": {
        "id": "34b91c1c-fbe4-4b05-8780-93ac67b3b041",
        "type": "CSAT"
      },
      "customer": null,
      "user": null,
      ...
    },
    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": {}
  }
}

This endpoint retrieves all ratings which belongs to the survey.

HTTP Request

GET https://api.nicereply.com/v1/surveys/<ID>/ratings

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the survey to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a survey stats

Response 200 OK

{
  "_results": {
    "average": 0,
    "count": 0
  }
}

OR

{
  "_results": {
    "nps_score": 0,
    "count": 0,
    "groups": {
      "promoters": 0,
      "passives": 0,
      "detractors": 0
    }
  }
}

This endpoint retrieves survey stats by metric type of survey.

HTTP Request

GET https://api.nicereply.com/v1/surveys/<ID>/stats

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the survey to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get a survey histogram

Response 200 OK

{
  "_results": {
    "histogram": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "7": 0,
      "8": 0,
      "9": 0,
      "10": 0
    }
  }
}

This endpoint retrieves survey histogram for all metric types.

HTTP Request

GET https://api.nicereply.com/v1/surveys/<ID>/histogram

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the survey to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get all unsubscribes

Response 200 OK

{
  "_results": [
    {
      "id": "3da978a0-5612-41f5-8b81-2cf3ffa467b8",
      "email": "customer3@example.com",
      "unsubscribed_at": "2021-08-23T14:21:02+02:00"
    },
    {
      "id": "4b6e4cd1-3314-4bb9-a752-2ee71a6875e7",
      "email": "customer2@example.com",
      "unsubscribed_at": "2021-08-21T01:23:44+02:00"
    },
    {
      "id": "e0cd54fc-18b0-4266-8d30-2e7bf90cf517",
      "email": "customer1@example.com",
      "unsubscribed_at": "2021-07-28T12:15:35+02:00"
    }
  ],
  "_pagination": {
    "total": 3,
    "count": 3,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all email unsubscribes.

HTTP Request

GET https://api.nicereply.com/v1/surveys/unsubscribes

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Teams

Team model fields

Field	Type	Description
id	string(UUID)	More about new IDs...
name	string
created_at	string	ISO8601 date

Get all teams

Response 200 OK

{
  "_results": [
    {
      "id": "ab27b8eb-444f-4e69-a2c3-734c2f6f5435",
      "name": "Team #2",
      "created_at": "2017-09-28T13:11:16+02:00",
      "_links": {
        "self": "/v1/teams/ab27b8eb-444f-4e69-a2c3-734c2f6f5435"
      }
    },
    {
      "id": "efa4bf41-16c5-4da2-adf6-2fe63fb512d1",
      "name": "Team #1",
      "created_at": "2017-10-24T13:37:01+02:00",
      "_links": {
        "self": "/v1/teams/efa4bf41-16c5-4da2-adf6-2fe63fb512d1"
      }
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your teams.

HTTP Request

GET https://api.nicereply.com/v1/teams

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Get stats for all teams

Response 200 OK

{
  "_results": [
    {
      "id": "1db5d455-40f7-401a-88f7-56ce56e8b760",
      "stats": {
        "CSAT": {
          "average": 0,
          "count": 0
        },
        "CES": {
          "average": 0,
          "count": 0
        },
        "NPS": {
          "nps_score": 0,
          "count": 0
        }
      }
    },
    {
      "id": "80cf7eb0-8b46-4f0b-b1fe-87d0562cb11c",
      "stats": {
        "CSAT": {
          "average": 0,
          "count": 0
        },
        "CES": {
          "average": 0,
          "count": 0
        },
        "NPS": {
          "nps_score": 0,
          "count": 0
        }
      }
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your teams with stats.

HTTP Request

GET https://api.nicereply.com/v1/teams/stats

Query Parameters

Parameter	Default	Description
period_start	none	Period start.
period_end	none	Period end.

Get users for all teams

Response 200 OK

{
  "_results": [
    {
      "id": "ab27b8eb-444f-4e69-a2c3-734c2f6f5435",
      "users": [
        {
          "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
          "type": "AGENT",
          "has_access": true,
          "is_archived": false,
          "username": "agentBob",
          "integration_usernames": [],
          "fullname": "Uncle Bob",
          "email": "unclebob@example.com",
          "role": "admin",
          "created_at": "2017-10-24T13:37:01+02:00",
          "_links": {
            "self": "/v1/users/d0cdf133-0a77-43cb-8c7c-127f8ecf154b"
          }
        }
      ]
    },
    {
      "id": "efa4bf41-16c5-4da2-adf6-2fe63fb512d1",
      "users": []
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all users which belongs to the team.

HTTP Request

GET https://api.nicereply.com/v1/teams/users

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Get a team

Response 200 OK

{
  "_results": {
    "id": "ab27b8eb-444f-4e69-a2c3-734c2f6f5435",
    "name": "Team #2",
    "created_at": "2017-09-28T13:11:16+02:00",
    "_links": {
      "self": "/v1/teams/ab27b8eb-444f-4e69-a2c3-734c2f6f5435"
    }
  }
}

This endpoint retrieves a specific team.

HTTP Request

GET https://api.nicereply.com/v1/teams/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the team to retrieve. More about IDs...

Get a team ratings

Response 200 OK

{
  "_results": [
    {
      "id": "0359f834-1909-4b59-bf35-f0c7428d2ee2",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "updated_at": "2017-10-24T13:37:01+02:00",
      "ticket": null,
      "survey": {
        "id": "a125739a-5c66-424f-9575-bbeae367522d",
        "type": "CSAT"
      },
      ...
    },
    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": {}
  }
}

This endpoint retrieves all ratings which belongs to the team.

HTTP Request

GET https://api.nicereply.com/v1/teams/<ID>/ratings

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the team to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a team stats

Response 200 OK

{
  "_results": {
    "CSAT": {
      "average": 0,
      "count": 0
    },
    "CES": {
      "average": 0,
      "count": 0
    },
    "NPS": {
      "nps_score": 0,
      "count": 0,
      "groups": {
        "promoters": 0,
        "passives": 0,
        "detractors": 0
      }
    }
  }
}

This endpoint retrieves team stats for all metric types.

HTTP Request

GET https://api.nicereply.com/v1/teams/<ID>/stats

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the team to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get a team histogram

Response 200 OK

{
  "_results": {
    "CSAT": {
      "histogram": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0,
        "6": 0,
        "7": 0,
        "8": 0,
        "9": 0,
        "10": 0
      }
    },
    "CES": {
      "histogram": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0,
        "6": 0,
        "7": 0
      }
    },
    "NPS": {
      "histogram": {
        "0": 0,
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0,
        "6": 0,
        "7": 0,
        "8": 0,
        "9": 0,
        "10": 0
      }
    }
  }
}

This endpoint retrieves team histogram for all metric types.

HTTP Request

GET https://api.nicereply.com/v1/teams/<ID>/histogram

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the team to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get a team users

Response 200 OK

{
  "_results": [
    {
      "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
      "type": "AGENT",
      "has_access": true,
      "is_archived": false,
      "username": "agentBob",
      "integration_usernames": [],
      "fullname": "Uncle Bob",
      "email": "unclebob@example.com",
      "role": "admin",
      "created_at": "2017-10-24T13:37:01+02:00",
      "_links": {
        "self": "/v1/users/d0cdf133-0a77-43cb-8c7c-127f8ecf154b"
      }
    }
  ],
  "_pagination": {
    "total": 1,
    "count": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": {}
  }
}

This endpoint retrieves all users which belongs to the team.

HTTP Request

GET https://api.nicereply.com/v1/teams/<ID>/users

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the team to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Users

User model fields

Field	Type	Description
id	string(UUID)	More about new IDs...
type	string(enum)	Valid values: AGENT, UNKNOWN_AGENT, THING_OR_ACTION
has_access	boolean	User is able to login to Nicereply
is_archived	boolean
username	string
integration_usernames	array	Array of integration_usernames objects
fullname	string
email	string
role	string(enum)	Valid values: admin, leader, team_member, restricted or (empty string = no role)
created_at	string	ISO8601 date

integration_usernames object fields

Field	Type	Nullable	Description
id	integer	No
username	string	No
type	string(enum)	No	Valid values: zendesk, zendeskChat, desk, desk-oauth, helpscout, helpscout-v2, salesforce, salesforce-v2, front, front-v2, freshdesk, liveagent, liveagent-v2, kayako, kayako-v2, teamsupport, deskpro, kustomer, otrs, bestpractical, groove, custom, shopify, intercom, gmail, outlook, mailchimp, aircall

Create a new Thing or Action

Response 201 Created

{
  "_results": {
    "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
    "type": "THING_OR_ACTION",
    "has_access": false,
    "is_archived": false,
    "username": "agentBob",
    "integration_usernames": [],
    "fullname": "Uncle Bob",
    "email": "",
    "role": "",
    "created_at": "2017-10-24T13:37:01+02:00",
    "_links": {
      "self": "/v1/users/d0cdf133-0a77-43cb-8c7c-127f8ecf154b"
    }
  }
}

This endpoint creates a new Thing or Action and return it to the response with HTTP status 201 Created.

HTTP Request

POST https://api.nicereply.com/v1/users/thing-or-action

BODY Parameters

Parameter	Required	Nullable	Type	Description
fullname	Yes	No	string
username	Yes	No	string

Create a new Agent

Response 201 Created

{
  "_results": {
    "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
    "type": "AGENT",
    "has_access": false,
    "is_archived": false,
    "username": "agentBob",
    "integration_usernames": [],
    "fullname": "Uncle Bob",
    "email": "unclebob@example.com",
    "role": "",
    "created_at": "2017-10-24T13:37:01+02:00",
    "_links": {
      "self": "/v1/users/d0cdf133-0a77-43cb-8c7c-127f8ecf154b"
    }
  }
}

This endpoint creates a new Agent without access and return it to the response with HTTP status 201 Created.

HTTP Request

POST https://api.nicereply.com/v1/users/agent

BODY Parameters

Parameter	Required	Nullable	Type	Description
fullname	Yes	No	string
username	Yes	No	string
email	Yes	No	string

Get all users

Response 200 OK

{
  "_results": [
    {
      "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
      "type": "AGENT",
      "has_access": true,
      "is_archived": false,
      "username": "agentBob",
      "integration_usernames": [
        {
          "id": "5e410892-9286-405f-b79f-ce109a23ba99",
          "username": "98463782636",
          "type": "zendesk"
        }
      ],
      "fullname": "Uncle Bob",
      "email": "unclebob@example.com",
      "role": "admin",
      "created_at": "2017-10-24T13:37:01+02:00",
      "_links": {
        "self": "/v1/users/d0cdf133-0a77-43cb-8c7c-127f8ecf154b"
      }
    },
    {
      "id": "c3553725-8315-439a-b68b-073193ee85e3",
      "type": "AGENT",
      "has_access": true,
      "is_archived": false,
      "username": "aaronwalker",
      "integration_usernames": [],
      "fullname": "Aaron Walker",
      "email": "aaronwalker@example.com",
      "role": "leader",
      "created_at": "2017-10-24T13:37:01+02:00",
      "_links": {
        "self": "/v1/users/c3553725-8315-439a-b68b-073193ee85e3"
      }
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your users.

HTTP Request

GET https://api.nicereply.com/v1/users

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.

Get stats for all users

Response 200 OK

{
  "_results": [
    {
      "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
      "stats": {
        "CSAT": {
          "average": 0,
          "count": 0
        },
        "CES": {
          "average": 0,
          "count": 0
        },
        "NPS": {
          "average": 0,
          "count": 0,
          "groups": {
            "promoters": 0,
            "passives": 0,
            "detractors": 0
          }
        }
      }
    },
    {
      "id": "c3553725-8315-439a-b68b-073193ee85e3",
      "stats": {
        "CSAT": {
          "average": 0,
          "count": 0
        },
        "CES": {
          "average": 0,
          "count": 0
        },
        "NPS": {
          "nps_score": 0,
          "count": 0,
          "groups": {
            "promoters": 0,
            "passives": 0,
            "detractors": 0
          }
        }
      }
    }
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": { }
  }
}

This endpoint retrieves all your users with stats.

HTTP Request

GET https://api.nicereply.com/v1/users/stats

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a user

Response 200 OK

{
  "_results": {
    "id": "d0cdf133-0a77-43cb-8c7c-127f8ecf154b",
    "type": "AGENT",
    "has_access": true,
    "is_archived": false,
    "username": "agentBob",
    "integration_usernames": [
      {
        "id": "5e410892-9286-405f-b79f-ce109a23ba99",
        "username": "98463782636",
        "type": "zendesk"
      }
    ],
    "fullname": "Uncle Bob",
    "email": "unclebob@example.com",
    "role": "admin",
    "created_at": "2017-10-24T13:37:01+02:00",
    "_links": {
      "self": "/v1/users/d0cdf133-0a77-43cb-8c7c-127f8ecf154b"
    }
  }
}

This endpoint retrieves a specific user.

HTTP Request

GET https://api.nicereply.com/v1/users/<ID>

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the user to retrieve. More about IDs...

Get a user ratings

Response 200 OK

{
  "_results": [
    {
      "id": "0359f834-1909-4b59-bf35-f0c7428d2ee2",
      "score": 5,
      "from": "Viktor Magic",
      "ip_address": "8.8.8.8",
      "comment": "Nice reply! :)",
      "created_at": "2017-10-24T13:37:01+02:00",
      "ticket": null,
      "survey": {
        "id": "a125739a-5c66-424f-9575-bbeae367522d",
        "type": "CSAT"
      },
      ...
    },
    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": {}
  }
}

This endpoint retrieves all ratings which belongs to the user.

HTTP Request

GET https://api.nicereply.com/v1/users/<ID>/ratings

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the user to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	created_at period start (ISO8601 date).
period_end	No	none	created_at period end (ISO8601 date).
updated_period_start	No	none	updated_at period start (ISO8601 date).
updated_period_end	No	none	updated_at period end (ISO8601 date).
sort_order	No	desc	Valid values is: asc or desc.

Get a user stats

Response 200 OK

{
  "_results": {
    "CSAT": {
      "average": 0,
      "count": 0
    },
    "CES": {
      "average": 0,
      "count": 0
    },
    "NPS": {
      "nps_score": 0,
      "count": 0,
      "groups": {
        "promoters": 0,
        "passives": 0,
        "detractors": 0
      }
    }
  }
}

This endpoint retrieves user stats for all metric types.

HTTP Request

GET https://api.nicereply.com/v1/users/<ID>/stats

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the user to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get a user histogram

Response 200 OK

{
  "_results": {
    "CSAT": {
      "histogram": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0,
        "6": 0,
        "7": 0,
        "8": 0,
        "9": 0,
        "10": 0
      }
    },
    "CES": {
      "histogram": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0,
        "6": 0,
        "7": 0
      }
    },
    "NPS": {
      "histogram": {
        "0": 0,
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0,
        "6": 0,
        "7": 0,
        "8": 0,
        "9": 0,
        "10": 0
      }
    }
  }
}

This endpoint retrieves user histogram for all metric types.

HTTP Request

GET https://api.nicereply.com/v1/users/<ID>/histogram

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the user to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
period_start	No	none	Period start (ISO8601 date).
period_end	No	none	Period end (ISO8601 date).

Get a user teams

Response 200 OK

{
  "_results": [
    {
      "id": "ab27b8eb-444f-4e69-a2c3-734c2f6f5435",
      "name": "Team #2",
      "created_at": "2017-09-28T13:11:16+02:00",
      "_links": {
        "self": "/v1/teams/ab27b8eb-444f-4e69-a2c3-734c2f6f5435"
      }
    },
    ...
  ],
  "_pagination": {
    "total": 2,
    "count": 2,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "links": {}
  }
}

This endpoint retrieves all teams which belongs to the user.

HTTP Request

GET https://api.nicereply.com/v1/users/<ID>/teams

URL Parameters

Parameter	Type	Description
ID	string(UUID)	The ID of the user to retrieve. More about IDs...

Query Parameters

Parameter	Required	Default	Description
sort_order	No	desc	Valid values is: asc or desc.