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 and emails may be specified.

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.

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"
  },
  "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"
  }
  ],
  "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."
    }
    ]
  }
  ]
}

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"
    },
    "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": [
    {
      "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
    }
    ]
  }
  ]
}"

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.

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"
    },
    "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
}
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.
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.

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.

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 made. For payments uploaded through the API this identifies the time that they have 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.

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"
}

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"
  },
  {
    "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"
  },
  {
    "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"
  },
  {
    "meta": {
      "id": "15151515151515151515151515151515",
      "timeCreated": 1385360134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": 785,
      "currency": "USD"
    },
    "payee": "TRUEACCORD",
    "transactionType": "PAYMENT"
  },
  {
    "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"
  }
 ]
}

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"
  },
  {
    "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"
  },
  {
    "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"
  },
  {
    "meta": {
      "id": "15151515151515151515151515151515",
      "timeCreated": 1385360134267
    },
    "debtId": "11111111111111111111111111111111",
    "amount": {
      "amount": 785,
      "currency": "USD"
    },
    "payee": "TRUEACCORD",
    "transactionType": "PAYMENT"
  },
  {
    "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"
  }
 ]
}

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"
}

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
303 2nd Street
Suite 750 South
San Francisco, CA 94107

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

TrueAccord Corp. is a Delaware corporation with offices in California.

©2017 TrueAccord. All Rights Reserved.

Better Business Bureau   Association of Credit and Collection Professionals