Recover API Reference
Introduction#
The TrueAccord Recover REST API allows you to interact with your Recover account programmatically. Currently, it allows you to upload customers and amounts to be recovered from them and query their most recent status.
All the requests to the API must be done over HTTPS.
Endpoint#
The endpoint for the TrueAccord Recover API is: https://api.trueaccord.com/api/v1/
Authentication#
You authenticate to the TrueAccord Recover API by providing your API key as a username using HTTP Basic Authentication. The password part is ignored.
Example:
The -u
option in curl sets the username and password for HTTP basic auth. Following it comes your API key and a colon that prevents curl from asking you for a password.
note
You must keep the colon (":") after your API key, as this represents a password which is being left blank.
You can also query the API in the browser with the same endpoint, https://api.trueaccord.com/api/v1/customers/. You'll be asked to provide a username and password in a pop-up alert. Copy-paste your API key into the username field, leave the password blank, and click the "Sign In" button. You'll see the JSON response in the browser window.
Headers#
X-TA-CREDITOR#
X-TA-CREDITOR
If your user account and its API key are associated with multiple creditors, you must include a custom header in your request for all /customer/
endpoints. Add the following header: --header "X-TA-CREDITOR: $RELEVANT_CREDITOR_ID"
.
If you fail to include this header, the request will fail with a status 403
error. See Recover Error Codes for more information.
If you're account is just associated with a single creditor, you do NOT need to include the X-TA-CREDITOR
header.
Customers Endpoints#
These endpoints deal with modifying information about Customers, i.e. those who owe money that TrueAccord attempts to collect.
See the Customer datatype for more information on the Customer object.
Add Customers#
One or more customers can be added in a single request. The request payload contains a list of Customers under the key "customers"
.
POST https://api.trueaccord.com/api/v1/customers/
Add Customers Query Parameters#
Param | Type | Required | Additional Information |
---|---|---|---|
addDebtsIfPossible | Boolean | Flag to add new debts to customers in the request for customers that have already been placed. |
Add Customers Request Body#
Key | Type | Required | Additional Information |
---|---|---|---|
customers | Array of Customers | ✅ | Include at least one Customer in the array. |
Adding Customers Example Request JSON Payload
Add Customers Responses#
200 OK#
The customers in the response will mirror those of your request but with an additional meta
field that can be used in the future to reference the customer objects you have created.
Key | Type | Required | Additional Info |
---|---|---|---|
customers | Array of Customers | New customers added to the system. | |
duplicatedReferences | Array of Duplicated References | If there are any duplicated customers in the query that have been placed before, their references will appear in the response under the duplicatedReferences field. | |
customersWithAddedDebts | Array of Customers | If addDebtsIfPossible is flagged in the request, the response will mirror your request with new customers, and also include a separate field for existing customers that had new debts added: customersWithAddedDebts . |
Add Customers 200 OK Response Example - Add New Customers and Duplicated References
Add Customers 200 OK Response Example - Only Duplicated References
Add Customers 200 OK Response Example - Existing Customer with Added Debts
Add Customers V2#
One or more customers can be added in a single request. The request payload contains a list of Customers under the key "customers"
. Use of V2 is recommended over V1, as it mirrors the request with results or errors per account.
POST https://api.trueaccord.com/api/v1/customersBatch/
Add Customers V2 Query Parameters#
Request body parameters available:
Key | Type | Required | Additional Info |
---|---|---|---|
addDebtsIfPossible | Boolean | If true , add new debts to customers in the request if they have already been placed. |
Adding Customers V2 Example Request
Add Customers V2 Responses#
200 OK#
In the case where the request succeeds, the response will mirror your request but with an additional meta
field that can be used in the future to reference the customer objects you have created.
If there are any duplicate references/transaction ids or any other issues with a placed customer, it will be visible in the response with the flag isError
.
If addDebtsIfPossible
is flagged, the response will mirror your request with new customers, and also include a flag for isAddedDebt
if an existing customer had another debt placed.
Key | Type | Required | Additional Info |
---|---|---|---|
responses | Array of objects | ✅ | Array that aligns with the request. Contains Customer V2 Responses and Customer V2 Errors. but if there was an error posting a certain customer, replaces that customer with an error message. |
Customer V2 Response#
Key | Type | Required | Additional Info |
---|---|---|---|
customer | Customer | ✅ | The customer that is added. |
isAddedDebt | Boolean |
Customer V2 Error#
Key | Type | Required | Additional Info |
---|---|---|---|
isError | Boolean | ✅ | Is true if there is an error. Can be used to programmatically identify when dealing with error. |
error | Error | ✅ | Information about the error returned. |
Adding Customers V2 200 OK Response Example - Add Customer and Duplicate Error
Adding Customers V2 200 OK Response Example - Only Duplicate Error
List Customers#
GET https://api.trueaccord.com/api/v1/customers/
Returns a paginated list of Customer objects you created, along with current status information.
List Customers Query Parameters#
Key | Type | Required | Additional Info |
---|---|---|---|
count | Integer | Number of results to return. Limited to at most 100. | |
offset | Integer | Zero-based. Used when more than 100 results to display further results. | |
startTime | Timestamp | Only returns customers after this time. | |
endTime | Timestamp | Only returns customers before this time. |
List Customers Responses#
200 OK#
Key | Type | Required | Additional Info |
---|---|---|---|
customers | Array of Customers | The customers returned by query. | |
totalResults | Integer | Total number of results for the query. Can be useful for pagination in combination with count and offset query parameters. |
Listing Customers Example Response - 200 OK
List Customers by Creditor Reference ID#
info
This section technically refers to the same endpoints as List Customer Responses. However, a separate section has been created for it due to the unique and important behavior of the reference
query parameter.
This will return a customer object specified by your internal reference number.
For one reference:
GET https://api.trueaccord.com/api/v1/customers/?reference={CreditorReferenceId}
For multiple references:
GET https://api.trueaccord.com/api/v1/customers/?reference={CreditorReferenceId_00},{CreditorReferenceId_01},...,{CreditorReferenceId_99}
List Customer by Creditor Reference ID Query Parameters#
Key | Type | Required | Additional Info |
---|---|---|---|
reference | comma separated strings | ✅ | Creditor's customer references. Separate multiple references with commas. Max number of references to include is 100. |
count | Integer | Number of results to return. Limited to at most 100. | |
offset | Integer | Zero-based. Used when more than 100 results to display further results. | |
startTime | Timestamp | Only returns customers after this time. | |
endTime | Timestamp | Only returns customers before this time. |
List Customers by Creditor Reference ID Responses#
200 OK#
Key | Type | Required | Additional Info |
---|---|---|---|
customers | Array of Customers | The customers returned by query. | |
totalResults | Integer | Total number of results for the query. Can be useful for pagination in combination with count and offset query parameters. |
List Customers by Creditor Reference ID 200 OK Response Example
Request endpoint: https://api.trueaccord.com/api/v1/customers/?reference=E=>7IzDYM
Response Body:
Get One Customer#
GET https://api.trueaccord.com/api/v1/customers/{customerId}
Returns the Customer object with the given customerId
.
The customer id appears in the meta field of the Customer object that was returned to you when you added the customer. The ids also appear in the list customers response.
Get One Customer Responses#
200 OK#
The response body is a Customer object, with the Metadata populated for all relevant fields.
Get One Customer 200 OK Response Example
Request Endpoint: `https://api.trueaccord.com/api/v1/customers/abcdefghijklmnop`Response body:
Add Contact Information to a Customer#
PATCH https://api.trueaccord.com/api/v1/customers/{customerId}
This will add the addresses, emails and phones in the request to the customer. Does not replace existing data.
Add Contact Information to a Customer Request Body#
If you do not want to add all addresses
, phones
, and emails
, you can just add as relevant. None of the fields are required.
Key | Type | Required | Additional Info |
---|---|---|---|
addresses | Array of Customer Addresses | ||
phones | Array of Customer Phones | ||
emails | Array of Customer Emails |
Add Contact Information to a Customer Request Body Example
Add Contact Information to a Customer Responses#
200 OK#
The response is a full Customer object for the customer with the customerId
in the URL parameter, including the contact information added in the request body.
Note that the response includes Metadata.
Add Contact Information to a Customer 200 OK Response Example
400 Bad Request - Improperly Formatted Data#
If any parts of the contact information are not properly formatted, the API returns a status 400
error with more information about why the data was not formatted correctly.
The response body is a Error object.
Add Contact Information to a Customer 400 Bad Request Response Example
Edit Contact Information for a Customer#
PUT https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID
This endpoint lets you change the name, date of birth, and language preference of the customer. It lets you insert, enable, and disable emails, phones, and addresses associated with the customer.
This is a PUT endpoint and so any information in the payload will be treated as the source of truth. Prior to calling this endpoint, please do a GET request to pull down the most recent information using the Get One Customer endpoint.
To disable an email/phone/address do not send it in the payload. To enable or insert an email/phone/address send the information in the payload. The difference between enabling and inserting is that enabling implies that the email/phone/address was already stored in our system.
Disabled emails/phones/addresses are kept in the system, and are visible in the response objects, with the meta.isActive
set to false
.
Addresses require meta.isActive
set to true
or false
.
Edit Contact Information for a Customer Request Body#
Key | Type | Required | Additional Info |
---|---|---|---|
name | Customer Name | ✅ | |
languagePreference | Language Enum | Note that the Language put here in languagePreference does not need to match with the language put in languagePreferred . However, it is recommended to align these for data consistency. | |
languagePreferred | Customer Language Preferred | ||
addresses | Array of Customer Addresses | ✅ | At least one address is required. |
phones | Array of Customer Phones | ||
emails | Array of Customer Emails | ✅ | At least one email is required. |
Language#
Enum | Notes |
---|---|
ENGLISH | |
SPANISH | |
FRENCH | |
MANDARIN | |
RUSSIAN | |
HAITIAN_CREOLE | |
BENGALI | |
ITALIAN | |
ARABIC | |
KOREAN | |
POLISH | |
CANTONESE | |
OTHER |
Customer Language Preferred#
Key | Type | Required | Additional Info |
---|---|---|---|
language | Language Enum | ||
languageChannel | Enum | One of:
| |
languageDate | Date |
Edit Demographic Information for a Customer Request Body Example
Edit Contact Information for a Customer Responses#
200 OK#
Response returns the full Customer object with updated information for the customer associated with the request. The response includes Metadata as applicable.