API Reference

Introduction

The TrueAccord REST API allows you to interact with your 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.

Authentication

You authenticate to the TrueAccord API by providing your API key as a username using HTTP Basic Authentication. The password part is ignored.

Example:

$ curl https://api.trueaccord.com/api/v1/customers/ -u $YOUR_KEY:

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.

You can also query the API using your browser. For example, you can visit https://api.trueaccord.com/api/v1/customers/. When you are asked to provide a username copy-paste your API key and leave the password blank.

Metadata

Most objects in our system contain a meta field with meta data describing the object.

id 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 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, lastModified Timestamps in milliseconds since Jan 1st, 1970 UTC. 
"meta": {
  "id": "3ef84ff19ddc",
  "isActive": true,
  "isPrimary": false,
  "timeCreated": 1385695523047,
  "lastModified": 1385695523047
}

Customers

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.

The Customer object

The following fields are mandatory: first and last name, address, and email. For best results, you should specify as many fields as possible in the Customers object.

Besides the above mandatory fields, all other fields are optional. If you have no value to supply for a field, you can omit it in your request.

Use the businesses array to provide one or more businesses names associated with this customer.

Similarly, one or more phones, addresses and emails may be specified.

The type of phone number can be specified by adding the types argument. Possible values are: HOME/WORK/CELL/FAX/BUSINESS. The types argument is optional and can be left blank if context doesn't exist.

The type of email can be specified by adding the types argument. Possible values are: HOME/WORK. The types argument is optional and can be left blank if context doesn't exist.

The type of address can be specified by adding the types argument. Possible values are: HOME/WORK. The types argument is optional and can be left blank if context doesn't exist.

The comments list can be used to provide us with context you may have about this customer.

Note that there are two comments lists. One inside the Customer object and the other one inside the Debt object. The latter can be used to provide information that is specific to the transaction and not about the customer itself.

reference is an arbitrary string that is used to attach your system's customer unique ID to this object. The string can be up to 1024 bytes long.

Finally, at least one debt must be specified.

The Debt object

Each Debt object contains the following fields:
biller for aggregators and marketplaces: this field stores the name of your sub merchant.
product description of the product or service associated with this debt.
initialPrincipal the amount of money owed to you, in cents. For example, specifying 14567 would imply a debt of $145.67. Currently, the only supported currency is USD. Our system will attempt to collect the total of initialPrincipal, initialInterest and initialFees.
initialInterest the amount of interest owed to you by this customer by the time it's handed off to TrueAccord.
initialFees the amount of fees owed to you by this customer due to not paying initialPrincipal.
transactionId arbitrary string of up to 1024 characters (aren't we being generous?) that you can use to store a reference to the transactionId on your system.
transactionIp IP address associated with this transaction. Either in IPv4 or IPv6 format.
transactionTimestamp time that the transaction leading to the debt occurred, if applicable. Format: milliseconds since Jan 1st, 1970 UTC. 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 time the customer defaulted on the debt, in milliseconds since Jan 1st, 1970 UTC. 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 time the customer initially opened or created an account with you, if applicable. In milliseconds since Jan 1st, 1970 UTC. 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 key-value pairs that are client specific
postChargeOffInformation information relevant for Post-ChargeOff debts. Required for accounts in the state of NY. The following data can be provided:
  • chargeOffTimestamp - the time of charge-off.
  • balanceAtChargeOff - the balance at time of charge-off.
  • feesAccruedSinceChargeOff - the fees accrued since time of charge-off.
  • interestAccruedSinceChargeOff - the interest accrued since time of charge-off.
  • totalPaidSinceChargeOff - the total amount paid since time of charge-off.

The Balance snapshot object

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.

principal is the new absolute value for the principal. The `amount` field is cents.

interest is the new absolute value for the interest. The `amount` field is cents.

fees is the new absolute value for the fees. The `amount` field is cents.

costs is the new absolute value for the costs. The `amount` field is cents.

notes is a note about why this balance has been updated.

Example object: 
{
  "principal": {
    "amount": 14567,
    "currency": "USD"
  },
  "interest": {
    "amount": 0,
    "currency": "USD"
  },
  "fees": {
    "amount": 132,
    "currency": "USD"
  },
  "costs": {
    "amount": 132,
    "currency": "USD"
  }
  "notes": "some note here"
}
Example object: 
{
  "name": {
    "firstName": "John",
    "middleName": "M",
    "lastName": "Groom"
  },
  "dateOfBirth": {
    "day": 7,
    "month": 2,
    "year": 1994
  },
  "businesses": [
  {
    "name": "Some Comp.",
    "url": "http://www.company.com"
  }
  ],
  "addresses": [
    {
      "streetLine1": "101 N First St",
      "streetLine2": "",
      "city": "San Jose",
      "state": "CA",
      "zipcode": "99999",
      "countryCode": "US",
      "types" : [ "HOME" ]
    }
  ],
  "phones": [
    {
      "phoneNumber": "650-999-9999",
      "types" : [ "CELL" ]
    }
  ],
  "emails": [
    {
      "email": "john@example.com",
      "types" : [ "WORK" ]
    },
    {
      "email": "john1977@gmail.com"
    }
  ],
  "comments": [
  {
    "comment": "Business owner."
  }
  ],
  "reference": "MyRef",
  "debts": [
  {
    "biller": "ArtsieStuff",
    "product": "Oil Painting",
    "initialPrincipal": {
      "amount": 14567,
      "currency": "USD"
    },
    "initialInterest": {
      "amount": 0,
      "currency": "USD"
    },
    "initialFees": {
      "amount": 132,
      "currency": "USD"
    },
    "transactionId": "MyTransId",
    "transactionIp": "192.168.14.30",
    "transactionTimestamp": 1385148285937,
    "defaultTimestamp": 1388563200000,
    "comments": [
    {
      "comment": "Transaction failed due to insufficient funds."
    },
    "clientFields": [{
      "key": "key1",
      "value": "val1"}
    ],
    "postChargeOffInformation" : {
      "chargeOffTimestamp" : 1388563200000,
      "balanceAtChargeOff" : {
        "amount": 14567,
        "currency": "USD"
      },
      "feesAccruedSinceChargeOff" : {
        "amount": 14567,
        "currency": "USD"
      },
      "interestAccruedSinceChargeOff" : {
        "amount": 14567,
        "currency": "USD"
      },
      "totalPaidSinceChargeOff" : {
        "amount": 14567,
        "currency": "USD"
      }
    }
    ]
  }
  ],
  "ssn": "123456789"
}

Adding 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/
Example request: 
$ curl https://api.trueaccord.com/api/v1/customers/ -u $YOUR_KEY: -d "{
  "customers":
  [
  {
    "name": {
      "firstName": "John",
      "middleName": "M",
      "lastName": "Groom"
    },
    "dateOfBirth": {
      "day": 7,
      "month": 2,
      "year": 1994
    },
    "businesses": [
    {
      "name": "Some Comp.",
      "url": "http://www.company.com"
    }
    ],
    "addresses": [
    {
      "streetLine1": "101 N First St",
      "streetLine2": "",
      "city": "San Jose",
      "state": "CA",
      "zipcode": "99999",
      "countryCode": "US",
      "types" : [ "HOME" ]
    }
    ],
    "phones": [
    {
      "phoneNumber": "650-999-9999",
      "types" : [ "CELL" ]
    }
    ],
    "emails": [
    {
      "email": "john@example.com",
      "types" : [ "WORK" ]
    },
    {
      "email": "john1977@gmail.com"
    }
    ],
    "reference": "MyRef",
    "debts": [
    {
      "biller": "ArtsieStuff",
      "product": "Oil Painting",
      "initialPrincipal": {
        "amount": 14567,
        "currency": "USD"
      },
      "initialInterest": {
        "amount": 0,
        "currency": "USD"
      },
      "initialFees": {
        "amount": 132,
        "currency": "USD"
      },
      "transactionId": "MyTransId",
      "transactionIp": "192.168.14.30",
      "transactionTimestamp": 1385148285937,
      "defaultTimestamp": 1388563200000,
      "postChargeOffInformation" : {
        "chargeOffTimestamp" : 1388563200000,
        "balanceAtChargeOff" : {
          "amount": 14567,
          "currency": "USD"
        },
        "feesAccruedSinceChargeOff" : {
          "amount": 14567,
          "currency": "USD"
        },
        "interestAccruedSinceChargeOff" : {
          "amount": 14567,
          "currency": "USD"
        },
        "totalPaidSinceChargeOff" : {
          "amount": 14567,
          "currency": "USD"
        }
      },
      "clientFields": [{
        "key": "key1",
        "value": "val1"}
      ]
    }
    ]
  }
  ],
  "addDebtsIfPossible": true
}"

Request body parameters available:

addDebtsIfPossible Optional boolean flag to add new debts to customers in the request if they have already been placed.

In 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 duplicated customers in the query that have been placed before, their references will appear in the response under the duplicatedReferences field.

If addDebtsIfPossible is flagged, the response will mirror your request with new customers, and also include a separate field for existing customers that had new debts added: customersWithAddedDebts.

Note:  If your user account is associated with multiple creditors, you must include a custom header in your request.  In Curl, add the following: --header "X-TA-CREDITOR: $RELEVANT_CREDITOR_ID".  If you fail to include this header, the request will fail.

Listing Customers

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

Will return a paginated list of Customer objects you created, along with current status information.

This endpoint accepts the params offset, count, startTime and endTime.

offset is zero-based, and count is the number of results to return which is limited to at most 100.

startTime and/or endTime will filter out customers that was not created within the specified range, it is supplied as milliseconds since Jan 1st, 1970 UTC.

Example response: 
{
  "totalResults": 1,
  "customers": [
  {
    "meta": {
      "id": "3ef84ff19ddc",
      "isActive": true,
      "isPrimary": false,
      "timeCreated": 1385695523047,
      "lastModified": 1385695523047
    },
    "name": {
      "firstName": "John",
      "middleName": "M",
      "lastName": "Groom"
    },
    "dateOfBirth": {
      "day": 7,
      "month": 2,
      "year": 1994
    },
    "businesses": [
    {
      "name": "Some Comp.",
      "url": "http://www.company.com"
    }
    ],
    "addresses": [
    {
      "streetLine1": "101 N First St",
      "streetLine2": "",
      "city": "San Jose",
      "state": "CA",
      "zipcode": "99999",
      "countryCode": "US"
    }
    ],
    "phones": [
    {
      "phoneNumber": "650-999-9999"
    }
    ],
    "emails": [
    {
      "email": "john@example.com"
    },
    {
      "email": "john1977@gmail.com"
    }
    ],
    "reference": "MyRef",
    "debts": [
    {
      "meta": {
        "id": "f32962a52aeb",
        "isActive": true,
        "isPrimary": false,
        "timeCreated": 1385695523047,
        "lastModified": 1385695523047
      },
      "biller": "ArtsieStuff",
      "product": "Oil Painting",
      "initialPrincipal": {
        "amount": 14567,
        "currency": "USD"
      },
      "initialInterest": {
        "amount": 0,
        "currency": "USD"
      },
      "initialFees": {
        "amount": 132,
        "currency": "USD"
      },
      "transactionId": "MyTransId",
      "transactionIp": "192.168.14.30",
      "transactionTimestamp": 1385148285937,
      "defaultTimestamp": 1388563200000,
      "accountNumber": "47994372839",
      "balance": {
        "amount": 14699,
        "currency": "USD"
      }
      "status": "New"
    }
    ]
  }
  ]
}

Note:  If your user account is associated with multiple creditors, you must include a custom header in your request.  In Curl, add the following: --header "X-TA-CREDITOR: $RELEVANT_CREDITOR_ID".  If you fail to include this header, the request will fail

Listing Customers by Reference ID

GET https://api.trueaccord.com/api/v1/customers/?reference=INTERNAL_REFERENCE_ID

This will return a customer object specified by your internal reference number.

GET https://api.trueaccord.com/api/v1/customers/?reference=REF0,REF1,...,REF99

You can list more than one customer in this way using the pattern in the GET-statement above. Do so by separating the reference ids in the query string with commas. Note that the API is limited to listing up to 100 customers in this way.

Note:  If your user account is associated with multiple creditors, you must include a custom header in your request.  In Curl, add the following: --header "X-TA-CREDITOR: $RELEVANT_CREDITOR_ID".  If you fail to include this header, the request will fail

Retrieving a Customer

GET https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID

Returns the Customer object with the given CUSTOMER_ID. 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 customers list response.

Listing Debts of a Customer

GET https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/

This endpoint accepts the following params startTime and endTime. startTime and/or endTime will filter out debts that has not been created within the specified range, it is supplied as milliseconds since Jan 1st, 1970 UTC.

Example response: 
{
  "debts": [
  {
    "meta": {
      "id": "00000000000000000000000000000000",
      "isActive": true,
      "timeCreated": 1385159134267,
    },
    "personId": "CUSTOMER_ID",
    "biller": "TheBiller",
    "product": "TheProduct",
    "initialPrincipal": {
      "amount": 14567,
      "currency": "USD"
    },
    "initialInterest": {
      "amount": 0,
      "currency": "USD"
    },
    "initialFees": {
      "amount": 132,
      "currency": "USD"
    },
    "status": "New",
    "transactionId": "MyTransId",
    "transactionIp": "192.168.0.1",
    "transactionTimestamp": 1385695523047,
    "defaultTimestamp": 1388563200000,
    "accountOpenTimestamp": 1385695523047,
    "accountNumber": "450000000",
    "balance": {
      "amount": 14699,
      "currency": "USD"
    },
  }
  ]
}

Add a New Debt to a Customer

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/
Example request: 
{
  "biller": "TheBiller",
  "product": "TheProduct",
  "initialPrincipal": {
    "amount": 14567,
    "currency": "USD"
  },
  "initialInterest": {
    "amount": 0,
    "currency": "USD"
  },
  "initialFees": {
    "amount": 132,
    "currency": "USD"
  },
  "transactionId": "MyTransId",
  "transactionIp": "192.168.0.1",
  "transactionTimestamp": 1385695523047,
  "defaultTimestamp": 1388563200000,
  "accountOpenTimestamp": 1385695523047,
  "clientFields": [{
    "key": "key1",
    "value": "val1"}
  ]
}
The response will be a debt object with a meta.id field which will be the debt permanent unique id. It is recommended to set the transactionId field to an invoice number on your system.

Retract a Debt from a Customer

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/retract
The request body should be empty. The response will be a debt object.

Query parameters available:

keepIfOnPaymentPlan default: true. Setting this to true will prevent the debt from being retracted if it is on a payment plan.
keepIfHasDispute default: true. Setting this to true will prevent the debt from being retracted if it has a dispute.
reason Optional field to add a retraction reason for the debt.
Example:
POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/retract?keepIfOnPaymentPlan=true&keepIfHasDispute=true

Retractions may result in fees. Please refer to the TOS and your contract, or email support@trueaccord.com for more details.

Soft Recall a Debt from a Customer

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/recalls
This endpoint is for submitting a soft recall notification for a debt.
Notice: this endpoint requires Soft Recall settings to be enabled in Creditor settings.
The request body should be empty.
The response will be a Soft Recall Response object.

Example response object: 
{
  "customerId": "11111111111111111111111111111111",
  "debtId": "22222222222222222222222222222222",
  "reason": "Recalling",
  "pendingRecallDate": {
    "day": 1,
    "month": 1,
    "year": 2000
  }
}

Query parameters available:

reason Optional field to add a retraction reason for the debt.
pendingRecallDate Optional field to add the future date on which the debt will be recalled. When not provided, the final recall date is assumed to be the current date plus the Days between soft and hard recall set in Creditor settings.

Constraints:
A provided pendingRecallDate must be set in the future, after the current time of the api call and not exceeding the current date plus the Days between soft and hard recall set in Creditor settings.
Example:
POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/recalls?pendingRecallDate=TIMESTAMP&reason=REASON

Re-open a Closed Debt

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/reopen
Use: Use this method if you wish to commence collections on an account that was closed in the past. 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. Note: The amounts should be in cents. Any missing fields will be assumed to have an amount of 0 USD. Example request: 
{
  "balance": {
    "principal": {
      "amount": 14567,
      "currency": "USD"
    },
    "interest": {
      "amount": 0,
      "currency": "USD"
    },
    "fees": {
      "amount": 132,
      "currency": "USD"
    },
    "costs": {
      "amount": 132,
      "currency": "USD"
    }
  }
}
The response, if successful, will be the updated debt object.

Updating a debt's total to collect balance

PUT https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/totalToCollectBalance

Example payload:

{
  "principal": {
    "amount": 14567,
    "currency": "USD"
  },
  "interest": {
    "amount": 0,
    "currency": "USD"
  },
  "fees": {
    "amount": 132,
    "currency": "USD"
  },
  "costs": {
    "amount": 132,
    "currency": "USD"
  }
  "notes": "some note here"
}

This will update the debt's total to collect balance to the absolute values specified in the payload. 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.

Example response:

{
  "principal": {
    "amount": 14567,
    "currency": "USD"
  },
  "interest": {
    "amount": 0,
    "currency": "USD"
  },
  "fees": {
    "amount": 132,
    "currency": "USD"
  },
  "costs": {
    "amount": 132,
    "currency": "USD"
  }
  "notes": "some note here"
}

Remember: the amounts are in cents.

Reading a debt's total to collect balance

GET https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/totalToCollectBalance

Example response:

{
  "principal": {
    "amount": 14567,
    "currency": "USD"
  },
  "interest": {
    "amount": 0,
    "currency": "USD"
  },
  "fees": {
    "amount": 132,
    "currency": "USD"
  },
  "costs": {
    "amount": 132,
    "currency": "USD"
  }
  "notes": "some note here"
}

This will return the debt's current total to collect 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.

Remember: the amounts are in cents.

Adding contact information to a customer

PATCH https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID

Example request:

{
  "addresses": [
  {
    "streetLine1": "101 N First St",
    "streetLine2": "",
    "city": "San Jose",
    "state": "CA",
    "zipcode": "99999",
    "countryCode": "US"
  }
  ],
  "phones": [
  {
    "phoneNumber": "650-999-9999"
  }
  ],
  "emails": [
  {
    "email": "john@example.com"
  },
  {
    "email": "john1977@example.com"
  }
  ]
}

This will add the addresses, emails and phones in the request to the customer. The response is a customer object which will mirror your request.

Editing Demographic Information for a Customer

PUT https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID

This endpoint will allow you change the name, date of birth, and language preference of the customer. It will also allow you to 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. 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.

Example GET (portion that is relevant):

{
  "name": {
    "firstName": "Example",
    "lastName": "John"
  },
  "dateOfBirth": {
    "day": 11,
    "month": 12,
    "year": 1997
  },
  "languagePreference": "ENGLISH",
  "addresses": [
    {
      "meta": {
        "isActive": true,
        "id": "2c8632aa4b054706b98197247cb59192",
        "timeCreated": 1576615694119,
        "isPrimary": false,
        "versionInfo": {
          "versionNumber": 0
        },
        "lastModified": 1576615694119
      },
      "state": "CA",
      "city": "City",
      "streetLine1": "St",
      "zipcode": "Zip",
      "countryCode": "US"
    }
  ],
  "phones": [
    {
      "meta": {
        "isActive": true,
        "id": "9f27657f5ae14d269f09f88f2d93d6cf",
        "timeCreated": 1576616142588,
        "isPrimary": false,
        "versionInfo": {
          "versionNumber": 0
        },
        "lastModified": 1576616142588
      },
      "phoneNumber": "1234567890"
    },
    {
      "meta": {
        "isActive": true,
        "id": "ad93da478af74d91bb4ba4ace53d1b44",
        "timeCreated": 1576615694214,
        "isPrimary": false,
        "versionInfo": {
          "versionNumber": 0
        },
        "lastModified": 1576615694214
      },
      "phoneNumber": "1234567891"
    },
    {
      "meta": {
        "isActive": false,
        "id": "b11a20b88f964cf8a143f6b790eba9d8",
        "timeCreated": 1576615694187,
        "isPrimary": false,
        "versionInfo": {
          "versionNumber": 0
        },
        "lastModified": 1576615694187
      },
      "phoneNumber": "1234567892"
    }
  ],
  "emails": [
    {
      "meta": {
        "isActive": false,
        "id": "0743356b34a149c792e12a9ba209ee11",
        "timeCreated": 1576615694176,
        "isPrimary": false,
        "versionInfo": {
          "versionNumber": 0
        },
        "lastModified": 1576615694176
      },
      "email": "john1@example.com"
    },
    {
      "meta": {
        "isActive": true,
        "id": "28ced3f7f7cf4b929c7059dabd260344",
        "timeCreated": 1576615694148,
        "isPrimary": false,
        "versionInfo": {
          "versionNumber": 0
        },
        "lastModified": 1576615694148
      },
      "email": "john2@example.com"
    }
  ]
}

Example request:

{
  "name": {
    "firstName": "John",
    "lastName": "Example"
  },
  "dateOfBirth": {
    "day": 12,
    "month": 11,
    "year": 1997
  },
  "languagePreference": "FRENCH",
  "addresses": [
    {
      "state": "CA",
      "city": "City",
      "streetLine1": "St",
      "zipcode": "Zip",
      "countryCode": "US"
    },
    {
      "state": "CA",
      "city": "City2",
      "streetLine1": "St2",
      "zipcode": "Zip2",
      "countryCode": "US"
    }
  ],
  "phones": [
    {
      "phoneNumber": "1234567891"
    },
    {
      "phoneNumber": "1234567892"
    },
    {
      "phoneNumber": "1234567893"
    }
  ],
  "emails": [
    {
      "email": "john1@example.com"
    },
    {
      "email": "john3@example.com"
    }
  ]
}

This request will change the name, date of birth, and language preference of the customer to the information in the payload. It will also insert a new address, disable the phone number (1234567890), enable the phone number (1234567892), insert the phone number (1234567893), enable the email (john1@example.com), disable the email (john2@example.com), and insert the email (john3@example.com).

Adding comments to a customer

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/comments

Example request:

{
    "comments": [
        "Customer only speaks spanish.  Usually they have a translator with them",
        "John has paid 100 dollars in the past"
    ]
}

This will add any creditor notes that the creditor wants to add. Please make sure that comments are only 500 characters long and we will only ingest a certain amount of comments at any given point

Removing contacts to a customer

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/unsubscribe

Example request:

{
  "addresses": [
    {
      "streetLine1": "101 N First St",
      "streetLine2": "",
      "city": "San Jose",
      "state": "CA",
      "zipcode": "99999",
      "countryCode": "US"
    }
  ],
  "phones": [
    {
      "phoneNumber": "650-999-9999"
    }
  ],
  "emails": [
    {
      "email": "john@example.com"
    },
    {
      "email": "john1977@example.com"
    }
  ]
}

This will unsubscribe any contact that is already included in our system. If it is not in our system you will need to upload it and then call this endpoint

Payments

The Payment object

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.

The payee identifies who received the payment and can take the following values:

CREDITOR
The payment has been made directly to the creditor.
TRUEACCORD
The payment has been made to TrueAccord.

The meta.timeCreated field identifies when the payment has been posted to TrueAccord.

Use transactionReference to associate this payment to a transaction in your internal system.

The transactionType identifies the type of this payment and can take the following values:

PAYMENT
A standard payment - this deducts the debt's balance. The amount must be positive.
RETURNED_PAYMENT
A payment that failed after it's been declared successful. This is typically used when ACH payments return, or when you refund customers. This payment increases the debt's balance, and the amount must be negative.
REFUND
A payment that has been refunded after it has been made. The amount is negative and it increases the debt's balance.

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.

The paymentTimestamp field is optional for informational purposee. if not provided during creation, it will return when the payment has been posted to TrueAccord. (matching meta.timeCreated)

Remember: the amounts are in cents.

Example object: 
{
  "meta": {
    "id": "11111111111111111111111111111111",
    "timeCreated": 1385159142788
  },
  "amount": {
    "amount": 300,
    "currency": "USD"
  },
  "payee": "TRUEACCORD",
  "transactionReference": "MyTransactionRef",
  "note": "Paid directly via CC",
  "transactionType": "PAYMENT",
  "paymentTimestamp" : 1448818320123
}

Listing Payments of Debt

GET https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/payments/

This endpoint accepts the following params startTime and endTime. startTime and/or endTime will filter out payments that has not been made within the specified range, it is supplied as milliseconds since Jan 1st, 1970 UTC.

Returns a list of all payments that have been made towards this debt.

Example response:

{
  "payments": [
  {
    "meta": {
      "id": "12121212121212121212121212121212",
      "timeCreated": 1385159134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": 785,
      "currency": "USD"
    },
    "payee": "CREDITOR",
    "transactionReference": "id_in_your_system",
    "note": "Paid part of the balance directly",
    "transactionType": "PAYMENT",
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "13131313131313131313131313131313",
      "timeCreated": 1385159134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": -345,
      "currency": "USD"
    },
    "payee": "NOBODY",
    "transactionReference": "",
    "note": "Increasing balance due to additional chargebacks.",
    "transactionType": "BALANCE_ADJUSTMENT"
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "14141414141414141414141414141414",
      "timeCreated": 1385160134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": -785,
      "currency": "USD"
    },
    "payee": "CREDITOR",
    "transactionReference": "id_in_your_system",
    "note": "The payment returned",
    "transactionType": "RETURNED_PAYMENT",
    "returnedPaymentId": "12121212121212121212121212121212"
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "15151515151515151515151515151515",
      "timeCreated": 1385360134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": 785,
      "currency": "USD"
    },
    "payee": "TRUEACCORD",
    "transactionType": "PAYMENT"
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "16161616161616161616161616161616",
      "timeCreated": 1385760134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": -785,
      "currency": "USD"
    },
    "payee": "TRUEACCORD",
    "note": "Payment was refunded by request of customer",
    "transactionType": "REFUND",
    "returnedPaymentId": "15151515151515151515151515151515"
    "paymentTimestamp" : 1448818320123
  }
 ]
}

Listing all Payments

GET https://api.trueaccord.com/api/v1/customers/payments/

Returns all payments that has been made.

This endpoint accepts the following params includeUnsettledPayments, startTime and endTime. includeUnsettledPayments defaults to false. startTime and/or endTime will filter out payments that has not been made within the specified range, it is supplied as milliseconds since Jan 1st, 1970 UTC.

Example response:

{
  "payments": [
  {
    "meta": {
      "id": "12121212121212121212121212121212",
      "timeCreated": 1385159134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": 785,
      "currency": "USD"
    },
    "payee": "CREDITOR",
    "transactionReference": "id_in_your_system",
    "note": "Paid part of the balance directly",
    "transactionType": "PAYMENT",
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "13131313131313131313131313131313",
      "timeCreated": 1385159134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": -345,
      "currency": "USD"
    },
    "payee": "NOBODY",
    "transactionReference": "",
    "note": "Increasing balance due to additional chargebacks.",
    "transactionType": "BALANCE_ADJUSTMENT"
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "14141414141414141414141414141414",
      "timeCreated": 1385160134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": -785,
      "currency": "USD"
    },
    "payee": "CREDITOR",
    "transactionReference": "id_in_your_system",
    "note": "The payment returned",
    "transactionType": "RETURNED_PAYMENT",
    "returnedPaymentId": "12121212121212121212121212121212"
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "15151515151515151515151515151515",
      "timeCreated": 1385360134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": 785,
      "currency": "USD"
    },
    "payee": "TRUEACCORD",
    "transactionType": "PAYMENT"
    "paymentTimestamp" : 1448818320123
  },
  {
    "meta": {
      "id": "16161616161616161616161616161616",
      "timeCreated": 1385760134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": -785,
      "currency": "USD"
    },
    "payee": "TRUEACCORD",
    "note": "Payment was refunded by request of customer",
    "transactionType": "REFUND",
    "returnedPaymentId": "15151515151515151515151515151515"
    "paymentTimestamp" : 1448818320123
  }
 ]
}

Note:  If your user account is associated with multiple creditors, you must include a custom header in your request.  In Curl, add the following: --header "X-TA-CREDITOR: $RELEVANT_CREDITOR_ID".  If you fail to include this header, the request will fail

Reporting a Payment of Debt

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/payments/

In order to update TrueAccord about a direct payment to the creditor, the payload of this request should be an object like this:

{
  "amount": {
    "amount": 785,
    "currency": "USD"
  },
  "payee": "CREDITOR",
  "transactionReference": "id_in_your_system",
  "note": "Paid part of the balance directly",
  "transactionType": "PAYMENT",
  "paymentTimestamp": 1448818320123 // optional field
}

For balance adjustments, please use the following route instead: PUT api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/totalToCollectBalance

If a payment returns (e.g. ACH payment or a refund), the transactionType RETURNED_PAYMENT should be used:

{
  "amount": {
    "amount": -785,
    "currency": "USD"
  },
  "payee": "CREDITOR",
  "transactionReference": "id_in_your_system",
  "note": "The ACH payment returned",
  "transactionType": "RETURNED_PAYMENT",
  "returnedPaymentId": "12121212121212121212121212121212"
}

In all cases the response would be a similar object containing a meta field with the unique permanent id of the payment.

Remember: the amounts are in cents.

Email: support@trueaccord.com or call us toll free at (866) 611-2731

TrueAccord
16011 College Blvd
Suite 130
Lenexa, KS 66219 USA

TrueAccord is a debt collection agency and this is an attempt to collect debt. Any information obtained will be used for that purpose.

©2020 TrueAccord. All Rights Reserved.

Better Business Bureau   Association of Credit and Collection Professionals