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 required fields of an address are the city, state, zipcode, and countryCode. The streetLine1 and streetLine2 fields should be populated if possible, streetLine1 being the street address and streetLine2 the PO box or apartment number.

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.

Adding 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/
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.
Example response:
{
  "responses": [
    {
      "customer": {
        "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"
              }
            ]
          }
        ]
      },
      "isAddedDebt": true
    },
    {
      "error": {
        "errorCode": "104",
        "message": "Duplicated transactionId.",
        "reference": "1234",
        "transactionId": "MyTransId"
      },
      "isError": true
    }
  ]
}

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 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.

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 .

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.
skipTerminalValidation default: false. Setting this to true will allow for retraction of terminal debts.
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.

Changing client fields

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

Example request body/response body:

{
    "clientFields": [
        {
            "key":"exampleKey",
            "value:"exampleValue"
        },
        {
            "key":"exampleKey2",
            "value:"exampleValue2"
        }
    ]
}

This will update the client fields on a debt object, overriding any existing fields.

Changing out of statute information

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

Example request body/response body:

{
    "explicitOutOfStatuteDate": {
        "day": 6,
        "month": 4,
        "year": 2012
    },
    "explicitOutOfStatuteFlag": true
}

This will update the out of statute information on a debt object, overriding any existing info.

explicitOutOfStatuteDate takes a JSON with day: Int, month: Int, and year: Int fields to represent the date the debt went out of statute.

explicitOutOfStatuteFlag is a boolean flag that can used with or without a date, in the case that an out of statute date is not available.

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.

Changing post charge off information

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

Example request body/response body:

{
    "postChargeOffInformation": {
        "balanceAtChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "interestAccruedSinceChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "nonInterestChargesAccruedSinceChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "feesAccruedSinceChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "totalPaidSinceChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "adjustmentsMadeSinceChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "lastPaymentAmountSinceChargeOff": {
            "amount":350,
            "currency":"USD"
        },
        "chargeOffTimestamp":1589578639958
    }
}

This will update the post charge off information on a debt object, overriding any existing info.

MonetaryAmount is a JSON with fields amount: Long, and currency: String -- currently the only supported currency is "USD".

balanceAtChargeOff: MonetaryAmount

interestAccruedSinceChargeOff: MonetaryAmount

nonInterestChargesAccruedSinceChargeOff: MonetaryAmount

feesAccruedSinceChargeOff: MonetaryAmount

totalPaidSinceChargeOff: MonetaryAmount

adjustmentsMadeSinceChargeOff: MonetaryAmount

lastPaymentAmountSinceChargeOff: MonetaryAmount

chargeOffTimestamp: Long -- Unix timestamp

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.

Pausing collections

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/pauseCollections?changeDebtStatus=BOOLEAN

Example request body:

{
    "reason": "OTHER",
    "pauseLengthInDays": 14,
    "notes": "Client needs a pause during recall process"
}

This will pause collections on an account, and change the debt's status to Paused if the param flag changeDebtStatus is set to true.

reason is a string from our list of internal reasons used to explain the reason for changingthe debt's status. These include: 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. 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.

pauseLengthInDays is an Int representing the number of days the account should remain paused. (0 indicates an indefinite pause period)

notes is a string used for notes related to pausing collections.

Unpausing collections

POST https://api.trueaccord.com/api/v1/customers/CUSTOMER_ID/debts/DEBT_ID/unpauseCollections?changeDebtStatus=BOOLEAN

Example request body:

{
    "notes": "Recall process is finished, unpausing"
}

This will unpause collections on an account, and change the debt's status to the last valid status, or New if no old status exists, if the param flag changeDebtStatus is set to true.

notes is a string used for notes related to unpausing collections.

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.

Seeing payment plans for a debt

GET https://api.trueaccord.com/api/v1/debts/:debtId/paymentPlans

Lists all active payment plans, and if the flag is set, all inactivated payment plans which were inactivated within the provided time window. Query parameters available:

from Start of time window in which the payment plan was inactivated
to End of time window in which the payment plan was inactivated
withInactivated Flag to include inactivated payment plans in response. Default = true

Example response:

[
{
"application": {
"originatingTokenId": "6edb055cbcf94dea8abb4f71bfac38f9",
"installments": [
{
"dueDate": 1590945962000,
"amount": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1593537962000,
"amount": {
"amount": 1000,
"currency": "USD"
}
},
{
"dueDate": 1596216362000,
"amount": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1598894762000,
"amount": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1601486762000,
"amount": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1604165162000,
"amount": {
"amount": 959,
"currency": "USD"
}
}
],
"paymentAmount": {
"amount": 980,
"currency": "USD"
},
"numberOfInstallments": 6,
"startDate": 1590945962000,
"frequency": "MONTHLY",
"consent": {
"ip": "0:0:0:0:0:0:0:1",
"time": 1590946543383
},
"debtId": "92101cfb7ef50724ed584d070eac4840",
"startCalendarDay": {
"day": 31,
"month": 5,
"year": 2020
},
"reason": "REQUEST_FOR_SPECIFIC_TERMS",
"createdByUserAccountId": "deadbeefdeadbeefdeadbeefdeadbeef",
"amountToPay": {
"amount": 5879,
"currency": "USD"
},
"discount": {
"amount": 0,
"currency": "USD"
}
},
"nextInstallment": 1,
"paymentMethodInfo": {
"cardInfo": {
"expirationMonth": "01",
"expirationYear": "2022",
"binNumber": "411111",
"billingZipCode": "94110",
"cardType": "VISA",
"lastFourDigits": "1111"
}
},
"revocation": {
"date": 1591035555387,
"reason": "REQUESTED_PLAN_CANCELLATION",
"revocationReason": "REQUESTED_PLAN_CANCELLATION"
},
"fullyPaid": false,
"installments": [
{
"installmentAmount": {
"amount": 980,
"currency": "USD"
},
"dueDate": 1590945962000,
"datePaid": 1590945993478,
"amountDue": {
"amount": 0,
"currency": "USD"
},
"status": "PAID_ON_TIME",
"isPaid": true
},
{
"dueDate": 1593537962000,
"status": "UNPAID",
"installmentAmount": {
"amount": 1000,
"currency": "USD"
},
"amountDue": {
"amount": 1000,
"currency": "USD"
}
},
{
"dueDate": 1596216362000,
"status": "UNPAID",
"installmentAmount": {
"amount": 980,
"currency": "USD"
},
"amountDue": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1598894762000,
"status": "UNPAID",
"installmentAmount": {
"amount": 980,
"currency": "USD"
},
"amountDue": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1601486762000,
"status": "UNPAID",
"installmentAmount": {
"amount": 980,
"currency": "USD"
},
"amountDue": {
"amount": 980,
"currency": "USD"
}
},
{
"dueDate": 1604165162000,
"status": "UNPAID",
"installmentAmount": {
"amount": 959,
"currency": "USD"
},
"amountDue": {
"amount": 959,
"currency": "USD"
}
}
],
"debtStateId": "6fef79e2339d4f9e83ee1eb61d42b634",
"isRecurring": true
}
]

Creditors

Listing a Creditors Brands

GET https://api/v1/creditors/CREDITOR_ID/brands/

This endpoint takes no params.

Returns a list of all existing brands for the url-supplied creditor id.

Example response:

{
  "type": "DOING_BUSINESS_AS",
  "name": "Existing Business",
  "address": {
    "streetLine2": "Suite #222",
    "state": "NV",
    "countryCode": "US",
    "city": "Las Vegas",
    "zipcode": "67676",
    "streetLine1": "222 Lane"
  },
  "meta": {
    "isPrimary": false,
    "id": "",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 0
    },
    "lastModified": 1589538329855,
    "timeCreated": 1589538329855
  },
  "description": "This business already exists.",
  "websiteUrl": "http://www.existentialbusiness.com"
},
{
  "logoUrl": "http://localhost/img/some_logo.png",
  "type": "ORIGINAL",
  "name": "Different Business",
  "address": {
    "streetLine2": "Suite #26",
    "state": "CA",
    "countryCode": "US",
    "city": "Differentville",
    "zipcode": "25806",
    "streetLine1": "160 Different Street"
  },
  "meta": {
    "isPrimary": false,
    "id": "55555555555555555555555555555555",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 0
    },
    "lastModified": 1589538329855,
    "timeCreated": 1589538329855
  },
  "description": "Not the same as existing business.",
  "websiteUrl": "http://www.differentialbusiness.com"
}

Updating Creditor Brands

PUT https://api/v1/creditors/CREDITOR_ID/brands

Returns a list of all brands, including any changes made by the call, or an error message describing the brand-level error preventing the update.

This endpoint takes no params.

The body of the request should be a an UpdateBrandsRequest object:

{
  "brands": [{
    "type": "DOING_BUSINESS_AS",
    "name": "Existing Business",
    "address": {
      "streetLine2": "Suite #222",
      "state": "NV",
      "countryCode": "US",
      "city": "Las Vegas",
      "zipcode": "67676",
      "streetLine1": "222 Lane"
    },
    "meta": {
      "isPrimary": false,
      "id": "",
      "isActive": true,
      "versionInfo": {
        "versionNumber": 0
      },
      "lastModified": 1589538329855,
      "timeCreated": 1589538329855
    },
    "description": "This business already exists.",
    "websiteUrl": "http://www.existentialbusiness.com"
  },
  {
    "logoUrl": "http://localhost/img/some_logo.png",
    "type": "ORIGINAL",
    "name": "Different Business",
    "address": {
      "streetLine2": "Suite #26",
      "state": "CA",
      "countryCode": "US",
      "city": "Differentville",
      "zipcode": "25806",
      "streetLine1": "753 Changed Different Street"
    },
    "meta": {
      "isPrimary": false,
      "id": "55555555555555555555555555555555",
      "isActive": true,
      "versionInfo": {
        "versionNumber": 0
      },
      "lastModified": 1589538329855,
      "timeCreated": 1589538329855
    },
    "description": "Not the same as existing business.",
    "websiteUrl": "http://www.differentialbusiness.com"
  },
  {
    "logoUrl": "http://www.website.com/logo.png",
    "type": "DOING_BUSINESS_AS",
    "name": "Another Different Business",
    "address": {
      "state": "IA",
      "countryCode": "US",
      "city": "Anotherville",
      "zipcode": "99995",
      "streetLine1": "1029 That Street"
    },
    "description": "Not the same either old business.",
    "websiteUrl": "http://www.consequentialbusiness.com"
  }]
}

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 meta data (with the exception of isActive, and isPrimary) cannot be provided, as it will be generated automatically. The ids of new brands will be returned as part of the successful response. Brands must have unique names, and unique Merchant/Original Creditor field pairs when applicable.

Example response:

{
  "type": "DOING_BUSINESS_AS",
  "name": "Existing Business",
  "address": {
    "streetLine2": "Suite #222",
    "state": "NV",
    "countryCode": "US",
    "city": "Las Vegas",
    "zipcode": "67676",
    "streetLine1": "222 Lane"
  },
  "meta": {
    "isPrimary": false,
    "id": "",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 0
    },
    "lastModified": 1589538329855,
    "timeCreated": 1589538329855
  },
  "description": "This business already exists.",
  "websiteUrl": "http://www.existentialbusiness.com"
},
{
  "logoUrl": "http://localhost/img/some_logo.png",
  "type": "ORIGINAL",
  "name": "Different Business",
  "address": {
    "streetLine2": "Suite #26",
    "state": "CA",
    "countryCode": "US",
    "city": "Differentville",
    "zipcode": "25806",
    "streetLine1": "753 Changed Different Street"
  },
  "meta": {
    "isPrimary": false,
    "id": "55555555555555555555555555555555",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 0
    },
    "lastModified": 1589538329855,
    "timeCreated": 1589538329855
  },
  "description": "Not the same as existing business.",
  "websiteUrl": "http://www.differentialbusiness.com"
},
{
  "logoUrl": "http://www.website.com/logo.png",
  "type": "DOING_BUSINESS_AS",
  "name": "Another Different Business",
  "address": {
    "state": "IA",
    "countryCode": "US",
    "city": "Anotherville",
    "zipcode": "99995",
    "streetLine1": "1029 That Street"
  },
  "meta": {
    "isPrimary": false,
    "id": "66666666666666666666666666666666",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 0
    },
    "lastModified": 1598538329851,
    "timeCreated": 1598538329851
  },
  "description": "Not the same either old business.",
  "websiteUrl": "http://www.consequentialbusiness.com"
}

Adding a New Creditor Brand

POST https://api/v1/creditors/CREDITOR_ID/brands

Returns a list of all brands, including the newly added brand, or an error message describing the brand-level error.

This endpoint takes no params.

The body of the request should be a single Brand object:

{
  "logoUrl": "http://localhost/img/logo.png",
  "type": "DOING_BUSINESS_AS",
  "name": "Business",
  "address": {
    "streetLine2": "Suite #123",
    "state": "CA",
    "countryCode": "US",
    "city": "San Francisco",
    "zipcode": "54321",
    "streetLine1": "789 Road"
  },
  "description": "Business business business.",
  "websiteUrl": "http://www.businessisgood.com"
}

Brand meta data (with the exception of isActive, and isPrimary) cannot be provided, as it will be generated automatically. The id of new brand will be returned as part of the successful response. Brands must have unique names, and unique Merchant/Original Creditor field pairs when applicable.

Example response:

{
  "type": "DOING_BUSINESS_AS",
  "name": "Existing Business",
  "address": {
    "streetLine2": "Suite #222",
    "state": "NV",
    "countryCode": "US",
    "city": "Las Vegas",
    "zipcode": "67676",
    "streetLine1": "222 Lane"
  },
  "meta": {
    "isPrimary": false,
    "id": "",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 1
    },
    "lastModified": 1589538329855,
    "timeCreated": 1589538329855
  },
  "description": "This business already exists.",
  "websiteUrl": "http://www.existentialbusiness.com"
},
{
  "logoUrl": "http://localhost/img/some_logo.png",
  "type": "ORIGINAL",
  "name": "Different Business",
  "address": {
    "streetLine2": "Suite #26",
    "state": "CA",
    "countryCode": "US",
    "city": "Differentville",
    "zipcode": "25806",
    "streetLine1": "160 Different Street"
  },
  "meta": {
    "isPrimary": false,
    "id": "55555555555555555555555555555555",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 3
    },
    "lastModified": 1589538329855,
    "timeCreated": 1589538329855
  },
  "description": "Not the same as existing business.",
  "websiteUrl": "http://www.differentialbusiness.com"
},
{
  "logoUrl": "http://localhost/img/logo.png",
  "type": "DOING_BUSINESS_AS",
  "name": "Business",
  "address": {
    "streetLine2": "Suite #123",
    "state": "CA",
    "countryCode": "US",
    "city": "San Francisco",
    "zipcode": "54321",
    "streetLine1": "789 Road"
  },
  "meta": {
    "isPrimary": false,
    "id": "66666666666666666666666666666666",
    "isActive": true,
    "versionInfo": {
      "versionNumber": 0
    },
    "lastModified": 1598538329851,
    "timeCreated": 1598538329851
  },
  "description": "Business business business.",
  "websiteUrl": "http://www.businessisgood.com"
}