Skip to content
ReplycoReplycoAPI

Look up a customer's history

Before your system answers a customer, or when it shows a customer’s record in your CRM, it helps to know what they have already discussed with your team. You find the customer by their email, name or your own id for them, then list their tickets and, if you use live chat, their chats.

Before you start

Section titled “Before you start”
Requirement Where to get it
An access token Sign in as a Replyco user of your company; see Authentication.
Something to search by An email address, phone number, name, or the id your system gave the customer.
The base URL https://open-api.replyco.com

How it works

Section titled “How it works”
  1. Find the customer.
  2. List their tickets.
  3. List their chats (optional).
sequenceDiagram
  participant app as Your app
  participant api as Replyco API
  app->>api: GET /openapi/customer/paged
  api-->>app: Find the customer
  app->>api: GET /openapi/thread/bycontact/{customerId}
  api-->>app: List their tickets
  opt List their chats
    app->>api: GET /openapi/chat/chatsbycustomer/{customerId}
    api-->>app: List their chats
  end

Step by step

Section titled “Step by step”

1. Find the customer

Section titled “1. Find the customer”

Call GET /openapi/customer/paged with what you know in term. It matches first and last names, email, phone and marketCustomerId, the customer’s id on the channel they came from.

Terminal window
curl "https://open-api.replyco.com/openapi/customer/paged?term=jane.smith@example.com&count=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response is a page: totalRecords, pageSize, pagesCount, currentPage, and the customers in data, each with id, names, email, phone, marketCustomerId, the integration they belong to and their address. A customer who wrote to you through several channels can appear once per channel. The id of the customer you mean is the customerId of the next steps.

A page holds 10 customers unless you send count, and at most 100: a larger count is rejected with 400.

2. List their tickets

Section titled “2. List their tickets”

Call GET /openapi/thread/bycontact/{customerId}.

Terminal window
curl "https://open-api.replyco.com/openapi/thread/bycontact/5c8a1e3f-7d2b-4f9c-8e6a-3b1d9f5c7e24?page=1&count=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response is a page of the customer’s tickets, the most recently opened first, 10 to a page unless you send count. Each ticket’s id is the threadId that GET /openapi/message/pagedthreadmessages/{threadId} takes to read its messages.

3. List their chats (optional)

Section titled “3. List their chats (optional)”

Skip this step when you do not use live chat. Otherwise call GET /openapi/chat/chatsbycustomer/{customerId}.

Terminal window
curl https://open-api.replyco.com/openapi/chat/chatsbycustomer/5c8a1e3f-7d2b-4f9c-8e6a-3b1d9f5c7e24 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response lists every chat the customer took part in, in one list. Each chat’s id is the chatId that GET /openapi/chat/pagedchatmessages/{chatId} takes. Sort the chats yourself if you need them in order.

What can go wrong

Section titled “What can go wrong”
Step Status Meaning What to do
any 401 The access token is missing or has expired. Refresh the token; see Authentication.
1 400 count is above 100. Ask for 100 customers or fewer per page.
1 429 Too many searches. Search with a more specific term instead of paging; see Rate limits.
2, 3 200, empty No tickets or chats for this id. Check that the id came from step 1; a customer with several channels may have their history under another of their records.
Section titled “Related”