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.
Edit Contact Information for a Customer 200 OK Response Example
400 Bad Request - Missing Information#
If any parts of the contact information are missing, the API returns a status 400 error with more information about what necessary data is missing.
The response body is a Error object.
Edit Contact Information for a Customer 400 Bad Request Response Example
Add Comments to a Customer#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/comments
Add comments to a Customer.
Add Comments to a Customer Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| comments | Array of Strings | ✅ | Max length for individual comment is 500 characters. The array of comments must contain less than 100 entries. In the event that the comments data doesn't meet these guidelines, the API returns a status 400 error. |
Add Comments to a Customer Request Body Example
Add Comments to a Customer Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
400 Bad Request - Invalid Data#
The response returns a 400 error when there are >99 comments or a comment contains >500 characters.
The response is an Error object.
Add Comments to a Customer 400 Bad Request Response Example
Unsubscribe Contact Information from a Customer#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/unsubscribe
Unsubscribe any contact that is already included in our system. When this endpoint is called, it changes the "isActive" field of the contact point to false.
If the contact point that you want us to not use is not already in the system, you need need to add it, and then call this endpoint. Contact information can be added with the Edit Contact Information for a Customer endpoint.
Unsubscribe Contact Information from a Customer Request Body#
Include combination of addresses, phones, and emails that you want unsubscribed. All Addresses, Phones, and Emails must be correctly formatted with their associated schemas or the request will return a status 400 with information about why the request failed.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| addresses | Array of Customer Addresses | ||
| phones | Array of Customer Phones | ||
| emails | Array of Customer Emails |
Unsubscribe Contact Information from a Customer Request Body Example
Unsubscribe Contact Information from a Customer Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
400 Bad Request - Invalid Data#
The response returns a 400 error when contact information is not formatted correctly.
The response is an Error object.
AUnsubscribe Contact Information from a Customer 400 Bad Request Response Example
Debts Endpoints#
These endpoints correspond to editing debt information for a given customer in the system.
The endpoints all start with the pattern: /customers/{customerId}/debts.
See the Debt datatype for more information on the Debt object.
List Debts of a Customer#
GET https://api.trueaccord.com/api/v1/customers/{customerId}/debts/
List Debts of a Customer Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| startTime | Timestamp | Only returns debts after this time. | |
| endTime | Timestamp | Only returns debts before this time. |
List Debts of a Customer Responses#
200 OK#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| debts | Array of Debts | ✅ | Debt objects include Metadata. |
info
When there are no debts in the response, such as if the query parameters you use filter for a range without any debts, the response returns an empty JSON object.
List Debts of a Customer 200 OK Response Example
Add New Debt to Customer#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/
Add New Debt to Customer Request Body#
The body of the request is a Debt object. While you must populate the required fields, the object returned for successful posts (see below 200 OK response) includes default values for a variety of fields.
info
It is recommended to set the transactionId field to an invoice number on your system.
Add New Debt to Customer Request Body Example
Responses#
200 OK#
The response will be a debt object with a meta.id field which will be the debt permanent unique id.
Add New Debt to Customer 200 OK Response Example
Retract Debt from Customer#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/retract
This stops the debt being collected by the TrueAccord system.
The debt remains in the system, but its "status" field is updated to be "status" : "RetractedByCreditor".
caution
Retractions may result in fees. Please refer to the TOS and your contract, or email support@trueaccord.com for more details.
Retract Debt from Customer Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| keepIfOnPaymentPlan | Boolean | Default is true. Setting this to true will prevent the debt from being retracted if it is on a payment plan. Setting this to false will return an error message to reach out to Trueaccord for retracting the debt. | |
| keepIfHasDispute | Boolean | Default is true. Setting this to true will prevent the debt from being retracted if it has a dispute. | |
| skipTerminalValidation | Boolean | Default is false. Setting this to true will allow for retraction of terminal debts. | |
| reason | String | Field to add a retraction reason for the debt. |
Example:
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/retract?keepIfOnPaymentPlan=true&keepIfHasDispute=true
Retract Debt from Customer Request Body#
The request body should be empty.
Retract Debt from Customer Responses#
200 OK#
The response will be a Debt object with "status" : "RetractedByCreditor".
Retract Debt from Customer 200 OK Response Example
422 Unprocessable Entity - Debt on Payment Plan#
If the debt is on a payment plan, and keepIfOnPaymentPlan=true, then it cannot be retracted via the API. (see above Retract Debt from Customer Query Parameters for more information.)
The response body is an Error object with code 422.
Retract Debt from Customer 422 Unprocessable Entity Example Response
Reopen Closed Debt#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/reopen
Use this method to restart collections on an account that was previously closed. For example, a settled account that accrued additional debt, or a retracted account that's being sent again to collections. The request body will be the desired balance of the debt, as seen in the following request example.
Reopen Closed Debt Request Body#
note
The amounts should be in cents. Only the balance.principle field is explicitly required. Any missing values for interest, fees, or costs will have a default value of 0 USD.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| balance | Balance Snapshot |
Reopen Closed Debt Request Example
Reopen Closed Debt Responses#
200 OK#
If successful the response is the Debt object that was referenced with the debtId in the endpoint, with updated debt balance information. The debt will have the field "status" : "New".
Reopen Closed Debt 200 OK Response Example
400 Bad Request - Debt on Payment Plan#
A debt cannot be reopened if it's already on an in-progress payment plan.
Response returns an Error object.
Reopen Closed Debt 400 Bad Request Debt on Payment Plan Response Example
400 Bad Request - Malformatted Balance#
Requests must contain properly formatted balance to be reopened.
If the balance isn't properly formatted, response returns an Error object.
Reopen Closed Debt 400 Bad Request Malformatted Balance Example
Bad request example:
Response example:
409 Conflict - Debt Status Incompatible with Reopening#
When debts are in terminal statuses, they cannot be reopened.
Response returns an Error object.
[DEPRECATED] Update Debt Total to Collect Balance#
PUT https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/totalToCollectBalance
DEPRECATED
The Update Debt Total to Collect Balance endpoint has been deprecated. It will always return a status 404 error response. See below Update Debt Total to Collect Balance Responses section for more information
Updates the debt's total to collect balance to the absolute values specified in the request payload.
Update Debt Total to Collect Balance Request Body#
The request body is a Balance Snapshot object.
Update Debt Total to Collect Balance Request Body Example
Update Debt Total to Collect Balance Responses#
404 Not Found#
The request returns an Error object as it has been deprecated.
Example:
Get Debt Total to Collect Balance#
GET https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/totalToCollectBalance
Return the debt's current total to collect balance.
Get Debt Total to Collect Balance Responses#
200 OK#
The response for successful requests is the Balance Snapshot for the Debt object.
Get Debt Total to Collect Balance 200 OK Response
Update Debt Client Fields#
PUT https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/clientFields
Update the client fields on a Debt object. This request overrides any existing client fields.
Update Debt Client Fields Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| clientFields | Array of ClientFields | ✅ | New values for client fields. |
Update Debt Client Fields Request Body Example
Update Debt Client Fields Responses#
200 OK#
The successful response mirrors the array of ClientFields included in the request.
Note that the response does not exactly mirror the request, as the response does not include the object with the key "clientFields".
Update Debt Client Fields 200 OK Response Example
400 Bad Request - Input Error#
If the request body is not formatted request, the API responds with status 400.
Update Debt Client Fields 400 Bad Request Input Error Response Example
Bad input request body:
Response:
Update Out of Statute Information#
PUT https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/outOfStatuteInformation
Update the out of statute information on a Debt object. Overrides any existing info.
Update Out of Statute Information Headers#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| X-TA-AUDIT-DESCRIPTION | String | Optional request header that can contain a free text description of the reason this create/update request is being called. Data will be shown in the version history of the created/updated entity. |
Update Out of Statute Information Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| explicitOutOfStatuteDate | Date | The date the debt goes out of statute. | |
| explicitOutOfStatuteFlag | Boolean | Flag that can used with or without a date, in the case that an out of statute date is not available to make a debt out of statute. |
Update Out of Statute Information Request Example
Update Out of Statute Information Responses#
200 OK#
Mirrors the request.
Update Out of Statute Information 200 OK Response Example
Update Post-Charge Off Information#
PUT https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/postChargeOffInformation
Update the post-charge off information on a debt object, overriding any existing info.
Update Post-Charge Off Information Headers#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| X-TA-AUDIT-DESCRIPTION | String | Optional request header that can contain a free text description of the reason this create/update request is being called. Data will be shown in the version history of the created/updated entity. |
Update Post-Charge Off Information Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| postChargeOffInformation | PostChargeOffInformation | New Post-charge off infomration for the debt. |
Update Post-Charge Off Information Example Request
Update Post-Charge Off Information Responses#
200 OK#
If the request is successful, the response mirrors the request.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| postChargeOffInformation | PostChargeOffInformation | ✅ | New Post-charge off infomration for the debt. |
Update Post-Charge Off Information Example Response 200 OK
Change Default Date#
PUT https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/defaultDate
Update the date the debt defaulted for a Debt object, overriding the existing defaultDate and defaultTimestamp. The timestamp will contain a time on the provided date which will keep the date consistent across all timezones.
Change Default Date Headers#
X-TA-AUDIT-DESCRIPTION is an optional request header that can contain a free text description of the reason this create/update request is being called. Data will be shown in the version history of the created/updated entity.
Change Default Date Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| defaultDate | Date | ✅ | Represents the calendar date the debt defaulted. |
Change Default Date Request Example
Change Default Date Responses#
200 OK#
A successful response mirrors the request.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| defaultDate | Date | ✅ | Represents the calendar date the debt defaulted. |
Change Default Date Response Example 200 OK
Pause Collections#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/pauseCollections?changeDebtStatus={BOOLEAN}
Pause collections on an account.
Pause Collections Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| changeDebtStatus | Boolean | Change debt's status to PAUSED if the param flag changeDebtStatus is set to true. |
Pause Collections Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| reason | Enum of PauseReason | ✅ | |
| pauseLengthInDays | Integer | Number of days the account should remain paused. 0 indicates an indefinite pause period. PauseLengthInDays should only be specified with TEMPORARY_HARDSHIP, OTHER or PROFANITY as the reason. | |
| notes | String | Reason why collections is being paused. Added as a comment on the Debt. |
Pause Collections Request Body Example
PauseReason#
Reason used to explain why the debt status has been changed to paused.
Some of these pause reasons have restrictions on number of days they can be paused for, so when a custom range of days is necessary, use OTHER or TEMPORARY_HARDSHIP, which lack these restrictions.
| Enum | Notes |
|---|---|
| SCRA | |
| PENDING_BK_VERIFICATION | |
| PENDING_FRAUD_INVESTIGATION | |
| PERMANENT_HARDSHIP_TERMINAL_ILLNESS | |
| PERMANENT_HARDSHIP_PERMANENT_DISABILITY | |
| PERMANENT_HARDSHIP_LONG_TERM_INCARCERATION | |
| TEMPORARY_HARDSHIP | |
| OTHER | |
| GEOGRAPHIC_SUPPRESSION | |
| GOOD_FAITH_PAYMENT | |
| INVALID_DISPUTE_PAUSE_PERIOD | |
| PROFANITY | |
| MAILED_IN_PAYMENT | |
| TEMPORARY_HARDSHIP_CONFIRMED | |
| DV_DOCS_MAILED | |
| PENDING_PREV_PAID_DOCS |
Pause Collections Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
400 Bad Request - Invalid Input#
When the input has an invalid format, suc has a missing required value, it returns a 400 error.
The response is an Error object.
Example response:
422 Unprocessable Entity#
When the request includes data that it shouldn't the response is a status 422 error.
The response is an Error object that contains more information about why the request couldn't be processed. The error msg field provides more detail about why the request was not successful.
Example, when you try to pause a debt already in a terminal status:
Unpause Collections#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/unpauseCollections?changeDebtStatus=BOOLEAN
Unpause collections on an account that has been paused.
Unpause Collections Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| changeDebtStatus | Boolean | If the param flag changeDebtStatus is set to true, change the debt's status to the last valid status, or NEW if no old status exists. |
Unpause Collections Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| notes | String | ✅ | Added as a comment on the debt regarding why collections is unpaused. |
Unpause Collections Request Body Example
Unpause Collections Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
422 Unprocessable Entity - Missing Required Fields#
When the input is missing a required value, it responds with a status 422 error.
The response is an Error object.
Example response:
Payments Endpoints#
These endpoints correspond to the Payment object. Payments correspond to changes to a Debt's balance.
List Payments of Debt#
GET https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/payments/
Return a list of all payments that have been made towards this debt, as specified by the debtId in the endpoint.
List Payments of a Debt Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| startTime | Timestamp | Only returns data after this time. | |
| endTime | Timestamp | Only returns data before this time. |
List Payments of a Debt Request Body#
No request body.
List Payments of a Debt Responses#
200 OK#
Returns all payments made to the debt.
If there have been no payments made on the debt or no payments in the time frame specified with the startTime and endTime query params, the response is just an empty object, {}.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| payments | Array of Payments |
List Payments of a Debt Response 200 OK Example
List All Payments#
GET https://api.trueaccord.com/api/v1/customers/payments/
Return all payments that have been made to a Creditor.
List All Payments Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| startTime | Timestamp | ✅ | Only returns data after this time. |
| endTime | Timestamp | ✅ | Only returns data before this time. |
| includeUnsettledPayments | Boolean | Default is false. |
List All Payments Responses#
200 OK#
Returns all payments made to the Creditor.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| payments | Array of Payments |
List All Payments Response 200 OK Example
400 Bad Request - Missing Required Query Parameters#
If the query parameters startTime and endTime are not included with the request, specifying a time window <90 days, the API responds with a status 400 error.
The response is an Error object.
Example response:
Report Payment of Debt#
POST https://api.trueaccord.com/api/v1/customers/{customerId}/debts/{debtId}/payments/
Update TrueAccord about a direct payment to the Creditor for a Debt.
Report Payment of Debt Request Body#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| amount | Monetary Amount | ✅ | |
| payee | String | ✅ | Should always be value "CREDITOR" |
| transactionReference | String | Reference to payment in your system. Not required, but strongly recommended for keeping your records in sync with TrueAccord. | |
| note | String | ||
| transactionType | Enum of TransactionType | ✅ | |
| paymentTimeStamp | Timestamp |
TransactionType#
| Enum | Notes |
|---|---|
| PAYMENT | Standard payment, applicable in most cases. |
| BALANCE_ADJUSTMENT | If a payment returns (e.g. ACH payment or a refund) use BALANCE_ADJUSTMENT. |
Report Payment of Debt Request Body Example
Report Payment of Debt Responses#
200 OK#
In all cases the response would be a similar object containing a meta field with the unique permanent id of the payment.
Report Payment of Debt 200 OK Response Example
400 Bad Response - Missing Required Fields#
If the request is missing any required fields of the request body, the API returns a status 400 error.
The response body is an Error object.
Example response:
List Payment Plans of Debt#
GET https://api.trueaccord.com/api/v1/debts/{debtId}/paymentPlans
List all active payment plans. If the withInactivated query parameter is set to true, also include all inactivated payment plans which were inactivated within the provided time window.
List Payment Plans of Debt Query Parameters#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| withInactivated | Boolean | Default is true. Flag to include inactivated payment plans in response. | |
| from | Timestamp | ✅ | Only use if withInactivated is true. Start of time window in which the payment plan was inactivated. |
| to | Timestamp | ✅ | Only use if withInactivated is true. End of time window in which the payment plan was inactivated. |
List Payment Plans of Debt Responses#
200 OK#
Returns array of all Payment Plans associated with the debt.
List Payment Plans of Debt Example 200 OK Response Example
400 Bad Request#
The List Payment Plans endpoint required the to and from query parameters, and if they're not included then the endpoint returns a status 400 error. That have correctly formatted values within the time the debt has been active.
The response returns an Error object if the time window is incorrect.
Example response for improper time window:
If the request misses either of the to or from parameters, then it returns an HTML document explaining the error.
Debt Representation Endpoints#
Get Attorney Representation#
GET https://api.trueaccord.com/api/v1/debts/{debtId}/representation/attorneyRepresentation
Get currently active attorney representation for a debt if it exists.
Get Attorney Representation Responses#
200 OK#
If the debt included in request, as specified by the debtId in the endpoint, has attorney representation, the response returns an Attorney Representation object.
Get Attorney Representation 200 OK with representation Response Example
If the debt included in the request does not have attorney representation, then the response contains the JavaScript value null.
Example:
Get Debt Consolidator Representation#
GET https://api.trueaccord.com/api/v1/debts/{debtId}/representation/debtConsolidatorRepresentation
Get currently active debt consolidator representation for a debt if it exists.
Get Debt Consolidator Representation Responses#
200 OK#
If the debt included in request, as specified by the debtId in the endpoint, has debt consolidator representation, the response returns a Debt Consolidator Representation object.
Get Debt Consolidator Representation 200 OK Response Example
If the debt included in the request does not have attdebt consolidator representation, then the response contains the JavaScript value null.
Example:
Add Attorney Representation#
POST https://api.trueaccord.com/api/v1/debts/{debtId}/representation/attorneyRepresentation
Add attorney representation for a debt.
Add Attorney Representation Request Body#
The request body is an Attorney Representation object.
Add Attorney Representation Request Body Example
Add Attorney Representation Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
Add Debt Consolidator Representation#
POST https://api.trueaccord.com/api/v1/debts/{debtId}/representation/debtConsolidatorRepresentation
Add Debt Consolidator Representation Request Body#
The request body is an Debt Consolidator Representation object.
Add Debt Consolidator Representation Request Body Example
Add Debt Consolidator Representation Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
Add Attorney Debt Consolidator Representation#
POST https://api.trueaccord.com/api/v1/debts/{debtId}/representation/attorneyDebtConsolidatorRepresentation
Add attorney debt consolidator representation for a debt. Based on creditor settings, will be treated as an attorney or a debt consolidator.
Verifying Creditor Settings Config Using the API
You can verify if the representation is added as attorney representation or debt consolidator representation by calling the Get Attorney Representation and Get Debt Consolidator Representation endpoints.
Whichever of the responses contains the representation included in the request to the Add Attorney Debt Consolidator Representation endpoint (this endpoint), is the configuration for this endpoint in the creditor settings.
Add Attorney Debt Consolidator Representation Request Body#
The request body is an Debt Consolidator Representation object.
Add Attorney Debt Consolidator Representation Request Body Example
Add Attorney Debt Consolidator Representation Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
Cancel Attorney Representation#
POST https://api.trueaccord.com/api/v1/debts/{debtId}/representation/cancelAttorneyRepresentation
Cancel attorney representation for a debt.
Cancel Attorney Representation Request Body#
The request body is a Representation Cancellation object.
Cancel Attorney Representation Request Body
Cancel Attorney Representation Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
400 Bad Request - No Attorney Representation#
If you try to cancel attorney representation for a debt that does not currently have attorney representation, the API responds with a status 400 error.
The response body is an Error object.
Example response:
Cancel Debt Consolidator Representation#
POST https://api.trueaccord.com/api/v1/debts/{debtId}/representation/cancelDebtConsolidatorRepresentation
Cancel debt consolidator representation for a debt.
Cancel Debt Consolidator Representation Request Body#
The request body is a Representation Cancellation object.
Cancel Debt Consolidator Representation Request Body
Cancel Debt Consolidator Representation Responses#
200 OK#
The response is JSON, however it is simply the string "ok".
Example response:
400 Bad Request - No Debt Consolidator Representation#
If you try to cancel debt consolidator representation for a debt that does not currently have debt consolidator representation, the API responds with a status 400 error.
The response body is an Error object.
Example response:
Creditors Endpoints#
List Creditor Brands#
GET https://api/v1/creditors/{creditorId}/brands/
List Creditor Brands Responses#
200 OK#
Returns a list of all existing brands for the creditorId in the URL.
The response schema is an array of Creditor Brand objects.
List Creditor Brands 200 OK Example Response
Update Creditor Brands#
PUT https://api/v1/creditors/{creditorId}/brands
Update Creditor Brands Request Body#
Existing brands may be updated, but their meta data (excluding isPrimary) and their type (Original/DBA) cannot be changed.
New brands may be added, but Metadata fields with the exception of isActive, and isPrimary cannot be provided, as it they be generated automatically. The ids of new brands will be returned as part of the successful response.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| brands | Array of Creditor Brands | ✅ | The array of brands must include all existing brands (which can be retrieved with the List Creditor Brands endpoint). The API will generate a status 400 error if all brands are not included. |
Update Creditor Brands Request Body Example
Update Creditor Brands Responses#
200 OK#
Returns a list of all brands, including any changes made by the call. Includes complete Metadata.
Update Creditor Brands 200 OK Response Example
400 Bad Request - Missing Required Values#
When the request body is missing required values, the API responds with a status 400 error.
The response body is a Error object.
Example response:
Add New Creditor Brand#
POST https://api/v1/creditors/{creditorId}/brands
Add New Creditor Brand Request Body#
The body of the request should be a single Creditor Brand object.
For Brand Metadata, only isActive, and isPrimary) can be provided. The other Metadata fields are generated automatically by the API. The id of new brand will be returned as part of the successful response.
note
You cannot add a new creditor brand with this endpoint that contains a name already possessed by another brand within the system. If you attempt to add a new brand with an existing brand name, the API responds with a status 400 response. See below Add Creditor Brands Responses for more details.
Add New Creditor Brand Request Body Example
Add Creditor Brands Responses#
Unsuccessful additions have an error message describing the brand-level error.
200 OK#
Returns the newly added Creditor Brand object with updated meta field.
Add Creditor Brands 200 OK Response Example
400 Bad Request - Improperly Formatted Request#
When the request body is malformatted, the API responds with a status 400 error.
The response body is a Error object.
Example response:
400 Bad Request - Duplicate Brand Names#
The request may not contain duplicate brand names. If you attempt to add another brand of the same name as an existing brand, the API responds with a status 400 error.
The response body is an Error object.
Example response:
Get Creditor Information#
GET https://api/v1/creditors/{creditorId}/info
Return creditor information for a given creditorId.
Get Creditor Information Responses#
200 OK#
The response body is a Creditor object.
Retrieving Creditor Information 200 OK Response Example
Data Types#
Attorney Representation#
Attorney Representation Specification#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| contactInfo | Contact Info | Attorney contact information. | |
| String | Email address for contacting the attorney. | ||
| requestedBy | Enum of RequestedBy | ||
| communicationType | Enum of CommunicationType | ||
| receivedPowerOfAttorneyDocumentation | Boolean |
RequestedBy#
| Enum | Notes |
|---|---|
| REQUEST_BY_UNKNOWN | |
| CUSTOMER | |
| POWER_OF_ATTORNEY | |
| CREDITOR | |
| DEBT_CONSOLIDATOR | |
| ATTORNEY | |
| TRUEACCORD | |
| ATTORNEY_DEBT_CONSOLIDATOR |
CommunicationType#
| Enum | Notes |
|---|---|
| COMMUNICATION_TYPE_UNKNOWN | |
| WRITTEN | |
| VERBAL |
Balance Snapshot#
The balance snapshot object represents an update to the debt's balance. This is the total to collect balance which means that it is the total amount for True Accord to collect on before any payments or credits.
Balance Snapshot Schema#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| principal | Monetary Amount | ✅ | The absolute value for the principal. |
| interest | Monetary Amount | The absolute value for the interest. If not provided in request, default value is 0. | |
| fees | Monetary Amount | The absolute value for the fees. If not provided in request, default value is 0. | |
| costs | Monetary Amount | The absolute value for the costs. If not provided in request, default value is 0. | |
| notes | String | A note about why this balance has been updated. |
Balance Snapshot Example#
Balance Snapshot Example Object
Contact Info#
Contact Info Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| name | String | ||
| phoneNumber | Phone Number | ||
| address | Contact Address |
Creditor#
Creditor Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| companyName | String | ||
| industry | String | ||
| environment | Enum of CreditorEnvironment | ||
| activationStatus | Enum of CreditorActivationStatus | ||
| commissionPercentBasisPoint | Integer |
CreditorActivationStatus#
| Enum | Notes |
|---|---|
| ACTIVE | Creditor is live |
| NOT_APPLIED | Initial mode for creditors who have signed up through the home page. They need to initiate an application to start the process. |
| APPLICATION_UNDER_REVIEW | The following are subject to change (DO NOT USE). |
| REJECTED | Terminal state for a creditor account - means that we didn't on-board this creditor. |
| OFFBOARDED | Terminal state for a creditor account - means that we collected for this creditor, and decided to terminate the relationship between us. |
CreditorEnvironment#
| Enum | Notes |
|---|---|
| LIVE | |
| TEST | |
| INTERNAL_TEST |
Creditor Example#
Creditor Brand#
Creditor Brand Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| logoUrl | String | ||
| type | Enum of CreditorBrandType | ✅ | Default: "DOING_BUSINESS_AS" |
| name | String | ✅ | |
| address | Postal Address | ||
| meta | Meta | ||
| description | String | ||
| websiteUrl | String | ||
| brandDetails | Brand Details | See note about unique fields on Brand Details. |
CreditorBrandType#
| Enum | Notes |
|---|---|
| DOING_BUSINESS_AS | An identity of the Creditor, under which it's doing business. |
| ORIGINAL | A brand that originally owned a debt, that the Creditor currently owns. Useful for debt buyer Creditors, as this brand represents one of the companies from which they bought debts. |
Brand Details#
Brand Details for each Creditor Brand must have unique merchant and originalCreditor field pairs, if Brand Details are included.
| Key | Type | Required | Additional Info |
|---|---|---|---|
| originalCreditor | String | Original Creditor for the debt. | |
| merchant | String | Original merchant associated with the debt. | |
| productType | Enum of ProductType |
Product Type#
| Enum | Notes |
|---|---|
| UNKNOWN | |
| CARD |
Creditor Brand Example#
Creditor Brand Example
Customer#
Customer objects represent a single person or business entity in our system. A single customer may be associated with more than one debt. The API allows you to create customers, list the customers you created as well as retrieving individual customers. Currently, updating or deleting an existing customer is unsupported.
Customer Specification#
tip
For best results in TrueAccord's collections attempts, you should specify as many fields as possible in the Customers object.
| Key | Type | Required | Additional Information |
|---|---|---|---|
| name | Name | ✅ | Full name of customer. |
| dateOfBirth | Date | When customer was born. | |
| businesses | Array of Customer Businesses | Any business names associated with the Customer. | |
| addresses | Array of Customer Addresses | ✅ | Must provide at least one Address. |
| phones | Array of Phone Numbers | Phone numbers associated with the Customer. | |
| emails | Array of Emails | ✅ | Must provide at least one Email. |
| comments | Array of Comments | Can be used to provide additional context about this customer. | |
| reference | String | Used to attach your system's customer unique ID to this object. Up to 1024 characters long. | |
| debts | Array of Debts | ✅ | Any existing debts associated with the customer. Must provide at least one Debt. |
| ssn | String | The Customer's Social Security Number. Should be formatted only as digits. (Ex: "123456789") |
Customer Business#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| name | String | Name of business. | |
| url | String | Website associated with business. Start with http(s)://.... |
Customer Address#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| streetLine1 | String | Street address. | |
| streetLine2 | String | Unit number or PO BOX. | |
| city | String | ✅ | City of address. |
| state | String | ✅ | Two-digit state code. Ex: "NY", "CA" |
| zipcode | String | ✅ | Postal code for address. |
| countryCode | String | ✅ | Code for country. Ex: "US" |
| types | Array of Enums | Array with one or both of the following:
|
Customer Phone#
While it is not required to provide a customer phone number, it is required to include the phoneNumber field if a phone number is provided.
| Key | Type | Required | Additional Information |
|---|---|---|---|
| phoneNumber | String | ✅ | Nine-digit phone number formatted ###-###-####. Ex: "444-555-6666" |
| types | Array of Enums | Array with one or more of the following:
|
Customer Email#
| Key | Type | Required | Value |
|---|---|---|---|
| String | ✅ | Must be valid email address. | |
| types | String | Array with one or more of the following:
|
Customer Example#
Customer Example Object
Data Source#
Data Source Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| type | Enum of DataSourceType |
DataSourceType#
| Enum | Notes |
|---|---|
| CREDITOR | Use when data is provided by creditor. This should always be used when it is the Creditor posting the information. |
| CUSTOMER | Used when the customer provides information directly to TrueAccord. |
Date#
Calendar date.
Date Schema#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| day | Integer | ✅ | Takes values 1-31. |
| month | Integer | ✅ | Takes values 1-12. |
| year | Integer | ✅ | 4-digit year, ex: 2021. |
Date Example#
Debt#
Each Debt object contains the following fields:
Debt Schema#
A debt object within the system. Our system will attempt to collect the total of initialPrincipal, initialInterest and initialFees.
The Debt data type has different schemas for the request and the response. The response has additional data and includes data provided in the request.
Debt Request Schema#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| biller | String | For aggregators and marketplaces: this field stores the name of your sub merchant. | |
| product | String | Description of the product or service associated with this debt. | |
| initialPrincipal | Monetary Amount | ✅ | Amount of money owed to you in cents. |
| initialInterest | Monetary Amount | ✅ | The amount of interest owed to you by this customer by the time it's handed off to TrueAccord. |
| initialFees | Monetary Amount | ✅ | The amount of fees owed to you by this customer due to not paying initialPrincipal. |
| transactionId | String | You can use to store a reference to the transactionId on your system. Up to 1024 characters. | |
| transactionIp | String | IP address associated with this transaction. Either in IPv4 or IPv6 format. | |
| transactionTimestamp | Timestamp | Time that the transaction leading to the debt occurred, if applicable. For example, the origination date of the loan or the date the customer purchased the product which led to the debt. This should be before the defaultTimestamp. Note that this date may be shown to the customer to provide context on the debt, and also has ramifications in our system's compliance rules. | |
| defaultTimestamp | Timestamp | Time customer defaulted on the debt. This should be after the transactionTimestamp. Note that this date may be shown to the customer to provide context on the debt, and also has ramifications in our system's compliance rules. | |
| accountOpenTimestamp | Timestamp | Time the customer initially opened or created an account with you, if applicable. Note that this date may be shown to the customer to provide context on the debt, and also has ramifications in our system's compliance rules. | |
| clientFields | Array of ClientFields | Key-value pairs that are client specific. | |
| sendCbrNegativeNotice | Boolean | Flag indicating whether a negative notice WILL BE submitted to a credit bureau in the future. | |
| hasSentCbrNegativeNotice | Boolean | Flag indicating whether a negative notice HAS BEEN submitted to a credit bureau in the past | |
| postChargeOffInformation | PostChargeOffInformation | Object with information relevant for Post-ChargeOff debts. Required for accounts in the state of NY. | |
| itemizationTimestamp | Timestamp | Unix Time in milliseconds, of the itemization date which could be any of last statement date, charge-off date, last payment date, transaction date, and judgement date. This is an optional field until the 30th Nov, 2021. | |
| initialPaymentsAndCredits | Monetary Amount | The monetary credits the customer has towards the debt, or the amount of money the customer has paid towards the debt, before the debt came to collections to Trueaccord. This is an optional field until the 30th Nov, 2021. | |
| isInitialPrincipalBeforePaymentsAndCredits | Boolean | Flag indicating whether the initialPrincipal includes initialPaymentsAndCredits. A "true" value indicates that the principal to be collected is initialPrincipal minus initialPaymentsAndCredits. A "false" value or the absence of the flag indicates that the principal to be collected is the initialPrincipal. This is an optional field until the 30th Nov, 2021. |
Debt Request Example#
Debt Request Example Object
Debt Response Schema#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| chargeOffStatus | Enum of ChargeOffStatus | ||
| biller | String | For aggregators and marketplaces: this field stores the name of your sub merchant. | |
| product | String | Description of the product or service associated with this debt. | |
| initialPrincipal | Monetary Amount | ✅ | Amount of money owed to you in cents. |
| initialFees | Monetary Amount | ✅ | The amount of fees owed to you by this customer due to not paying initialPrincipal. |
| accountNumber | String | ||
| accountOpenTimestamp | Timestamp | Time the customer initially opened or created an account with you, if applicable. Note that this date may be shown to the customer to provide context on the debt, and also has ramifications in our system's compliance rules. | |
| creditorId | String | UUID set by TrueAccord system. | |
| personId | String | UUID set by TrueAccord system. | |
| meta | Metadata | ||
| defaultTimestamp | Timestamp | Time customer defaulted on the debt. This should be after the transactionTimestamp. Note that this date may be shown to the customer to provide context on the debt, and also has ramifications in our system's compliance rules. | |
| itemizationTimestamp | Timestamp | Unix Time in milliseconds, of the itemization date which could be any of last statement date, charge-off date, last payment date, transaction date, and judgement date. This is an optional field until the 30th Nov, 2021. | |
| initialPaymentsAndCredits | Monetary Amount | The monetary credits the customer has towards the debt, or the amount of money the customer has paid towards the debt, before the debt came to collections to Trueaccord. This is an optional field until the 30th Nov, 2021. When this field is not provided in the request, a zero value is considered. | |
| isInitialPrincipalBeforePaymentsAndCredits | Boolean | Flag indicating whether the initialPrincipal includes initialPaymentsAndCredits. A "true" value indicates that the principal to be collected is initialPrincipal minus initialPaymentsAndCredits. A "false" value or the absence of the flag indicates that the principal to be collected is the initialPrincipal. This is an optional field until the 30th Nov, 2021. | |
| transactionTimestamp | Timestamp | Time that the transaction leading to the debt occurred, if applicable. For example, the origination date of the loan or the date the customer purchased the product which led to the debt. This should be before the defaultTimestamp. Note that this date may be shown to the customer to provide context on the debt, and also has ramifications in our system's compliance rules. | |
| initialInterest | Monetary Amount | ||
| type | Enum of DebtType | ||
| initialCost | Monetary Amount | ||
| clientFields | Array of ClientFields | Key-value pairs that are client specific. | |
| transactionId | String | You can use to store a reference to the transactionId on your system. Up to 1024 characters. | |
| transactionIp | String | IP address associated with this transaction. Either in IPv4 or IPv6 format. | |
| status | String | ||
| creditor | Creditor | ||
| balanceDetails | Balance Details | ||
| maxDiscountPercent | Integer | Maximal discount creditor is willing to give. Percent integer, out of 100. Deprecated in favor of effectiveMaxDiscountPercent. | |
| internalConfiguration | Internal Configuration | ||
| transactionIdLast4 | String | Last 4 digits of transactionId. | |
| accountNumberForDisplay | String | ||
| prohibitedActions | Array of Prohibited Actions | ||
| accruedInterest | Monetary Amount | Portion of the balance that comes from interest. | |
| balance | Monetary Amount | ||
| placementType | Enum of PlacementType | ||
| paymentPlanId | String | The identifier for the related payment plan, if it exists. | |
| balanceDetailsAtPlacement | Balance Snapshot | ||
| availablePaymentMethods | Available Payment Methods | ||
| specialUiTreatment | Enum of SpecialUiTreatment | ||
| isPreLegal | Boolean | ||
| communicationsInformation | Communications Information | ||
| unsettledPaymentsAmount | Monetary Amount | Total amount of unsettled payments that have not cleared yet. They do not contribute to the balance at this point. | |
| isTimebarCompliant | Boolean | ||
| minSettlementPercent | Integer | Percent integer, out of 100. | |
| initialTotal | Monetary Amount | Beware potentially misleading name. Sums the debt's balance buckets "to collect". Balance to collect = initial balance + balance adjustments. where initial balance is the sum of initial principal, initial interest, etc. So this is "total balance to collect", sum of "total principal to collect", "total interest to collect", etc. | |
| locationCreated | Location Created | Total amount of unsettled payments that have not cleared yet. They do not contribute to the balance at this point. | |
| effectiveMaxDiscountPercent | Effective Max Discount Percent | ||
| recentTransactionInfo | Recent Transaction Info |
Debt Response Example#
Debt Response Example Object
PostChargeOffInformation#
The following data can be provided:
| Key | Type | Required | Additional Information |
|---|---|---|---|
| chargeOffTimestamp | Timestamp | The time of charge-off. | |
| balanceAtChargeOff | Monetary Amount | The balance at time of charge-off. | |
| feesAccruedSinceChargeOff | Monetary Amount | The fees accrued since time of charge-off. | |
| interestAccruedSinceChargeOff | Monetary Amount | The interest accrued since time of charge-off. | |
| totalPaidSinceChargeOff | Monetary Amount | The total amount paid since time of charge-off. |
Balance Details#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| principal | Monetary Amount | ||
| interest | Monetary Amount | ||
| fees | Monetary Amount | ||
| costs | Monetary Amount | ||
| overcharges | Monetary Amount | Represents mistakes in which TrueAccord collected more than the balance. | |
| isSettledInFull | Boolean |
Internal Configuration#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| showSpecialDisputeTreatment | Boolean | Whether TrueAccord shows special presentation for dispute debt state that this debt has. Applicable in states that require special disclosures or procedures for disputes. |
Prohibited Action#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| debtAction | Enum of DebtActions | ||
| prohibitedReasons | Array of Enum ProhibitionReasons |
DebtAction#
Actions that can be performed on a given debt. This varies depending on the debt's status and the creditor lifecycle stage.
| Enum | Notes |
|---|---|
| NEW_PAYMENT | |
| NEW_PAYMENT_PLAN | |
| MAKE_COMMUNICATION | |
| NEW_PART_PAYMENT |
ProhibitionReason#
| Enum | Notes |
|---|---|
| DEBT_TERMINAL | |
| CREDITOR_STATUS | |
| LOCATION | |
| PENDING_PAYMENT |
Available Payment Methods#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| creditCard | Boolean | ||
| debitCard | Boolean | ||
| check | Boolean |
Communications Information#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| hadInitialCommunication | Boolean | ||
| requiredCommunicationClauses | Enum | The requiredCommunicationClauses field is used by certain creditors that require an additional communication with the initial communication. Request additional information from TrueAccord if you believe that this is necessary to you. |
Location Created#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| physical | Postal Address |
Effective Max Discount Percent#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| overrideType | Enum of OverrideType | ||
| maxDiscountPercent | Maximal discount creditor is willing to give. Percent with max of 100. | ||
| maxSettlementPercent | 100 minus max discount percent. |
OverrideType#
| Enum | Notes |
|---|---|
| NO_OVERRIDE | |
| CREDITOR | |
| PORTFOLIO | |
| DEBT | |
| HEARTBEAT |
Recent Transaction Info#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| lastChargeDate | Date | ||
| lastChargeAmount | Monetary Amount | ||
| lastPaymentDate | Date | ||
| lastPaymentAmount | Monetary Amount |
ChargeOffStatus#
| Enum | Notes |
|---|---|
| NONE | NONE means 'unset'. |
| PRE_CHARGE_OFF | Indicates that the debts are provided to TrueAccord before the creditor charges them off from their books, and writes them as loss. |
| POST_CHARGE_OFF | Indicates that the debts are provided to us after being charged off from the creditor's books. Some states have extra regulation for collecting on debts of this status. |
DebtType#
The high-level types of debts handled by the system.
| Enum | Notes |
|---|---|
| DEBT_TYPE_NONE | |
| DEBT_TYPE_COMMERCIAL | |
| DEBT_TYPE_CONSUMER |
PlacementType#
| Enum | Notes |
|---|---|
| ORIGINAL | |
| ORIGINAL |
SpecialUiTreatment#
| Enum | Notes |
|---|---|
| PURCHASED |
ClientField#
Custom client-specific data.
| Key | Type | Required | Additional Information |
|---|---|---|---|
| key | String | ✅ | The key specifying the type of information. |
| value | String | ✅ | The value containing the information. |
Debt Consolidator Representation#
Debt Consolidator Representation Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| debtConsolidatorType | Enum of DebtConsolidatorType | ||
| contactInfo | Contact Info | ||
| String | Email address for contacting the debt consolidator. | ||
| requestedBy | Enum of RequestedBy | ||
| communicationType | Enum of CommunicationType | ||
| receivedPowerOfAttorneyDocumentation | Boolean | ||
| offerPercentOfBalance | Integer | ||
| offerDurationInMonths | Integer |
Debt Consolidator Representation Example#
Debt Consolidator Representation Example
DebtConsolidatorType#
debtConsolidatorType must be selected from a predetermined list on our backend. If you'd like to use a debt consolidator that isn't listed, use OTHER or get in contact with TrueAccord to add a new one.
| Enum | Notes |
|---|---|
| CREDIT_SOLUTIONS | |
| FREEDOM_FINANCIAL | |
| AMERICAN_FREEDOM_FINANCIAL | |
| DEBT_SETTLEMENT_USA | |
| US_DEBT_RELIEF | |
| ACCELERATE_DEBT_MANAGEMENT_GROUP | |
| PACIFIC_DEBT | |
| NATIONAL_DEBT_RELIEF | |
| CHRISTIAN_DEBT_REMOVERS | |
| LIBERTY_SETTLEMENT_GROUP | |
| CORPORATE_TURNAROUND | |
| LAW_OFFICES_OF_MATTHEW_GUTHRIE | |
| SEIDELMAN_PALMER | |
| JASON_HASS_GROUP | |
| ROLL_LAW_OFFICE | |
| OTHER |
Duplicated Reference#
The Duplicated Reference data type is used in response to Add Customers requests when there already is an account in the system for your creditor profile with the same Customer reference or a Debt associated with the customer with the same Debt transactionId.
Duplicated Reference Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| reference | String | Refers to the reference field in the Customer data type. | |
| transactionId | String | Refers to the transactionId field in the Debt data type. |
Duplicated Reference Example#
Error#
These Error objects are returned when data cannot be ingested, but there was not any HTTP response error (i.e status 4XX/5XX). This error object is returned with status 200 OK responses.
For more information about status 4XX/5XX errors, and the associated responses, refer to the Recover API Error Documentation.
Error Schema#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| errorCode | String | ✅ | Error code about why data could not be ingested. More information about these codes can be found in the Recover API error code documentation. |
| message | String | ✅ | |
| reference | String |
Error Example#
Metadata#
Most objects in our system contain a meta field with meta data describing the object.
Metadata Schema#
| Key | Type | Additional Information |
|---|---|---|
| id | String | Unique identifier of the object in our system. You should treat this as an opaque string and not rely on its format. |
| isActive | Boolean | Field which indicates whether an object is active in the system. If a customer or a debt are inactive, our system will not attempt to collect them. |
| isPrimary | Boolean | If the object appears in a list of objects (like emails, or phones) this indicates whether that object has priority over others. There can be at most one primary object in a list. |
| timeCreated | Timestamp | When object was created. Should not be included in REQUESTS to the API. The TrueAccord system will generate this. |
| lastModified | Timestamp | When object was last modified. Should not be included in REQUESTS to the API. The TrueAccord system will generate this. |
Metadata Example#
Monetary Amount#
The Monetary Amount object is the way that money is represented in the TrueAccord system. Monetary Amounts are always in cents.
Monetary Amount Specification#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| amount | Integer | ✅ | Amount of money in cents. |
| currency | String | ✅ | Currency of Monetary Amount. Currently the system only supports "USD". |
Monetary Amount Example#
Name#
A person's name.
Name Specification#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| firstName | String | ✅ | Customer first name. |
| middleName | String | Customer middle name. | |
| lastName | String | ✅ | Customer last name. |
Name Example#
Payment#
The payment object represents a change in the debt's balance. Every payment has an amount associated with it. A positive amount decreases the debt balance while a negative amount increases the balance.
Payment Specification#
| Key | Type | Required | Additional Information |
|---|---|---|---|
| meta | Meta | Only includes "id" and "timeCreated". | |
| amount | Monetary Amount | ✅ | The amount of the payment. Must be positive. |
| payee | Enum | ✅ | Identifies who received the payment and can take the following values:
|
| transactionReference | String | Reference to associate this payment to a transaction in your internal system. | |
| note | String | Note about the payment. If no note is provided in the request, the API responds with the "note": "Received from the API". | |
| transactionType | Enum | ✅ | Identifies the type of this payment and can take the following values:
|
| paymentTimestamp | Timestamp | Optional for informational purposes. If not provided during creation, it will return when the payment has been posted to TrueAccord. (matching meta.timeCreated) | |
| returnedPaymentId | Timestamp | Returned payments must contain a returnedPaymentId field to indicate which payment returned, out of those that have been reported to TrueAccord. Notice: the id is of TrueAccord's system. Use Listing Payments of Debt to retrieve the list of previously reported payments. | |
| isFailed | Boolean | Only returned by the API. true if there was a problem making the payment. |
Payment Example#
Payment Example Object
Payment Plan#
A payment plan is a scheduled series of payments for a customer to repay their Debt.
Payment Plan Specification#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| application | Payment Plan Application | ||
| nextInstallment | Number | Index of the next installment to be paid. | |
| paymentMethodInfo | Payment Method Info | ||
| revocation | Payment Plan Revocation | ||
| fullyPaid | Boolean | True if payment plan fully paid. Can also be calculated from the installments. | |
| Installments | Array of Payment Plan Installments | ||
| debtStateId | String | ||
| isRecurring | Boolean |
Payment Plan Application#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| originatingTokenId | String | ||
| installments | Array of Payment Plan Application Installments | ||
| numberOfInstallments | Integer | DEPRECATED - Use the size of the 'installments' array field. Number of installments expected to be paid during the plan. | |
| startDate | Timestamp | DEPRECATED - This value is only used by the backend to calculate the explicit installments for backwards compatibility. It is not used if the explicit installments are set and will eventually not be used at all. The start date of the plan (this is when the first installment is due) | |
| frequency | Enum of Payment Plan Frequency | Frequency of payment as originally set. Only used by the backend if the installments field is not set. | |
| consent | Consent | ||
| debtId | String | The debtId this application refers to. | |
| startCalendarDay | Date | The start calendar day. Useful to avoid timezone-related issues and know the customer's true intended start date. | |
| reason | String | Default: OTHER | |
| createdByUserAccountId | String | ||
| amountToPay | Monetary Amount | The principal amount that needs to be paid for completing this plan. Normally, this would be the debt balance at time of consent - discount. However, in case of revocation and reapplying that amount may include fees accrued from the previous time. | |
| discount | Monetary Amount | The discount offered by us as an absolute number. The amount_to_pay field above reflects that discount. We store it here since this number is displayed in the plan terms. |
Payment Plan Frequency#
| Enum | Notes |
|---|---|
| UNKNOWN | |
| WEEKLY | |
| BI_WEEKLY | |
| MONTHLY | |
| CUSTOM |
Payment Plan Application Installment#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| dueDate | Timestamp | ||
| amount | Monetary Amount |
Consent#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| ip | String | String representation of IP address. Ex: "0:0:0:0:0:0:0:1" | |
| time | Timestamp | ✅ | Time consent was given. |
Payment Method Info#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| cardInfo | Payment Card Info | ||
| achInfo | ACH Info |
Payment Card Info#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| expirationMonth | String String | Month card expiring. Takes values 01-12. Ex: "03 | |
| expirationYear | String | Year card expiring. Four digits. Ex: "2022". | |
| binNumber | String | Payment card BIN. | |
| billingZipCode | String | ZIP code associated with the payment card. | |
| cardType | Enum of PaymentCardType | Issuer of the payment card. Takes values | |
| lastFourDigits | String |
PaymentCardType#
| Enum | Notes |
|---|---|
| UNKNOWN | |
| MASTERCARD | |
| VISA | |
| DISCOVER |
ACH Info#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| lastThreeOfAccountNumber | String | ||
| lastFourOfAccountNumber | String |
Payment Plan Revocation#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| date | Timestamp | ||
| reason | String | ||
| revocationReason | Enum of Revocation Reason | Default is "MISC_REMOVAL" |
Revocation Reason#
| Enum | Notes |
|---|---|
| MISC_REMOVAL | |
| PLAN_BREAKAGE | |
| NEW_PLAN_REQUEST | |
| REQUESTED_PLAN_CANCELLATION | |
| IN_DISPUTE | |
| CLIENT_RETRACTED | |
| CLOSED | |
| ALTERNATIVE_RESOLUTION |
Payment Plan Installment#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| dueDate | Timestamp | ||
| datePaid | Timestamp | Empty if not paid. | |
| isPaid | Boolean | ||
| isIvrPayment | Boolean | ||
| isEnteredByAgent | Boolean | ||
| paymentMethod | Enum of Payment Method | ||
| status | Enum of Payment Status | ||
| installmentAmount | Monetary Amount | ||
| amountDue | Monetary Amount | Amount left to be paid for this installment (0 if installment is fully paid). |
Payment Method#
| Enum | Notes |
|---|---|
| CARD | |
| ACH | |
| CHECK | |
| DIRECT2CREDITOR | |
| OTHER |
Payment Status#
| Enum | Notes |
|---|---|
| UNPAID | Unpaid payment. |
| UNPAID_OVER_DUE | Within grace period. |
| UNPAID_LATE | |
| PAID_ON_TIME | Paid before or during grace period. |
| PAID_LATE |
Phone Number#
Phone Number Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| phoneNumber | String | The phone number to be used for contacting. | |
| dataSource | Data Source | ||
| consent | Consent | ||
| types | Array of Enums | Array with one or more of the following:
|
Phone Number Example#
Postal Address#
Postal Address Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| name | Name | ||
| streetLine1 | String | Street address. | |
| streetLine2 | String | Unit number or PO BOX. | |
| city | String | ✅ | City of address. |
| state | String | ✅ | Two-digit state code. Ex: "NY", "CA" |
| zipcode | String | ✅ | Postal code for address. |
| countryCode | String | ✅ | Code for country. Ex: "US" |
Representation Cancellation#
Representation Cancellation Schema#
| Key | Type | Required | Additional Info |
|---|---|---|---|
| requestedBy | Enum of RequestedBy | ||
| communicationType | Enum of CommunicationType | ||
| reason | String |
Representation Cancellation Example#
Timestamp#
TrueAccord uses timestamps to mark time in it's system that are in milliseconds since Jan 1st, 1970 UTC.