# Customers

Customers represent Debtors. You can attach one or more Debt Accounts to the Customer. Creating Customers allows them to login to the Portal and pay off Debt.

# Create Customer

POST https://<org-uuid>.production.tratta.io/api/v1/customers

curl https://<org-uuid>.production.tratta.io/api/v1/customers \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d name="Customer Name" \
 -d email="test@email.com"

# Parameters

name required|string

Name of the customer. For example, first name and last name or company name.

email string|email

Email of the customer.

external_id optional|string

External id of customer in the 3rd party application.

phone optional|string|US

US Phone number of customer.

date_of_birth optional|date

Date of birth of customer in the format 1991-12-31

ssn_last4 optional|number

last 4 digits of customer Social security number

address optional

name optional|string
line1 optional|string
line2 optional|string
city optional|string
postal_code optional|string
state optional|string
country optional|string
is_primary optional|boolean

metadata optional|key:max:255|value:max:255

Json object of key value pairs for meta data you may want to attach to customer object.

# Returns

A json with data property that contains created customer object.

{
  "id": "string",
  "external_id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "date_of_birth": "date",
  "ssn": "string",
  "address": [{
    "name": "string",
    "city" : "string",
    "postal_code" : "string",
    "country" : "string",
    "line1" : "string",
    "line2" : "string",
    "state" : "string",
    "is_primary": "boolean"
  }],
  "metadata": [{
    "attribute": "key",
    "value": "value"
  }, {
    "attribute": "key1",
    "value": "value"
  }]
}

# Update Customer

PUT https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d name="Updated Customer Name" \
 -X PUT

# Parameters

name string

Name of the customer. For example, first name and last name or company name.

email string|email

Email of the customer.

external_id string

External id of customer in the 3rd party application.

phone string|US

US Phone number of customer.

date_of_birth optional|date

Date of birth of customer in the format 1991-12-31

ssn_last4 optional|number

last 4 digits of customer Social security number

address object

id optional|string
name string
line1 string
line2 string
city string
postal_code required (only when id doesnt exist)|string
state string
country string
is_primary optional|boolean

metadata optional|key:max:255|value:max:255

Key value pairs can be updated, when you PUT to the key a different value. When you PUT an empty value to existing key, it will be deleted. When you put and empty value to whole metadata, all of the metadata associated with customer object will be deleted.

# Get Customer

GET https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Parameters

id required_if:external_id missing|string

Uuid of customer provided from Tratta when Creating Customer object. This url parameter is required only if the external_id wasn't provided instead.

external_id required_if:id missing|string

External id of customer provided by you through external_id parameter when Creating Customer object. This url parameter is required only if the id wasn't provided instead.

# Returns

A json with data property that contains created customer object.

{
  "id": "string",
  "external_id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "date_of_birth": "date",
  "ssn": "string",
  "addresses": [
    {
      "name": "string",
      "city": "string",
      "postal_code": "string",
      "country": "string",
      "line1": "string",
      "line2": "string",
      "state": "string",
      "is_primary": "boolean"
    }
  ],
  "metadata": [
    {
      "attribute": "key",
      "value": "value"
    },
    {
      "attribute": "key1",
      "value": "value"
    }
  ]
}

# List Customers

GET https://<org-uuid>.production.tratta.io/api/v1/customers

curl https://<org-uuid>.production.tratta.io/api/v1/customers \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Returns

A json with data property that contains array of customer objects.

{
  "id": "string",
  "external_id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "date_of_birth": "date",
  "ssn": "string",
  "addresses": [
    {
      "name": "string",
      "city": "string",
      "postal_code": "string",
      "country": "string",
      "line1": "string",
      "line2": "string",
      "state": "string",
      "is_primary": "boolean"
    }
  ],
  "metadata": [
    {
      "attribute": "key",
      "value": "value"
    },
    {
      "attribute": "key1",
      "value": "value"
    }
  ]
}

# Delete Customer

DELETE https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/customers \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -X DELETE

# Returns

{
  "success": "boolean"
}

# Create Customer Address

GET https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d name="Updated Address Name" \
 -d is_primary=false \
 -X POST

# Parameters

name optional|string

country optional|string

city optional|string

state optional|string

postal_code required|string|5 digits

line1 optional|string

line2 optional|string

is_primary optional|string

is_primary determines if this the primary address of the customer. Defaults to false, but set to true when creating the first address for the customer. A customer can have only one primary address at any given time.

# Returns

{
    "id": "string",
    "name": "string",
    "city": "string",
    "postal_code": "string",
    "country": "string",
    "line1": "string",
    "line2": "string",
    "state": "string",
    "is_primary": "boolean"
}

# List Customer Addresses

GET https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Parameters

id required_if:external_id missing|string

Uuid of customer provided from Tratta when Creating Customer object. This url parameter is required only if the external_id wasn't provided instead.

# Returns

{
    "id": "string",
    "name": "string",
    "city": "string",
    "postal_code": "string",
    "country": "string",
    "line1": "string",
    "line2": "string",
    "state": "string",
    "is_primary": "boolean"
}

# Update Customer Address

PUT https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses/{addressId}

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses/{addressId} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d name="Updated Address Name" \
 -d is_primary=true \
 -X PUT

# Parameters

id required_if:external_id missing|string

Uuid of customer provided from Tratta when Creating Customer object. This url parameter is required only if the external_id wasn't provided instead.

addressId required

uuid of address provided by Tratter when Creating Customer object

name optional|string

country optional|string

city optional|string

state optional|string

postal_code required|string|5 digits

line1 optional|string

line2 optional|string

is_primary optional|string

# Returns

{
    "id": "string",
    "name": "string",
    "city": "string",
    "postal_code": "string",
    "country": "string",
    "line1": "string",
    "line2": "string",
    "state": "string",
    "is_primary": "boolean"
}

# Delete Customer Address

DELETE https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses/{addressId}

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id/external_id}/addresses/{addressId} \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -X DELETE

# Parameters

id required_if:external_id missing|string

Uuid of customer provided from Tratta when Creating Customer object. This url parameter is required only if the external_id wasn't provided instead.

addressId required

uuid of address provided by Tratter when Creating Customer object

# Returns

{
  "success": "boolean"
}

# Create Customer Payment Method

POST https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id}/payment-methods

Create a payment method for a customer. You can create either a card or ACH payment method.

# Card Example

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id}/payment-methods \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d card[card_holder]="John Doe" \
 -d card[card_number]="4242424242424242" \
 -d card[card_expiration_month]="12" \
 -d card[card_expiration_year]="25" \
 -d card[card_security_code]="123" \
 -d card[card_postal_code]="10001"

# ACH Example

curl https://<org-uuid>.production.tratta.io/api/v1/customers/{id|external_id}/payment-methods \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d ach[account_holder]="John Doe" \
 -d ach[account_type]="checking" \
 -d ach[routing_number]="021000021" \
 -d ach[account_number]="123456789" \
 -d ach[account_zip]="10001" \
 -d ach[account_state]="NY"

# Parameters

card json object with paramters

card_holder required without ach
card_number required without ach|valid card number
card_expiration_month required without ach|numeric|between:1,12
card_expiration_year required without ach|last 2 digits of a year
card_security_code optional
card_postal_code optional|5 digits

ach json object with parameters

account_holder required without card
account_type required without card|in:checking, savings

Checking or Savings account type.
routing_number required without card|valid routing number
account_number required without card|min:4|max:17
account_zip required without card|5 digits

Specifies the Postal code of the account.
account_state required without card

# Returns

A json with data property that contains created payment_method object.

{
  "id": "string",
  "type": "card|ach",
  "card_token": {
    "card_holder": "string",
    "card_number": "string",
    "expiration_month": "string",
    "expiration_year": "string",
    "card_type": "string",
    "card_zip": "string"
  },
  "bank_account": {
    "account_holder": "string",
    "account_type": "string",
    "ownership_type": "string",
    "routing_number": "string",
    "account_number": "string",
    "account_zip": "string",
    "account_state": "string"
  },
  "is_primary": "boolean",
  "created_at": "string",
  "updated_at": "string"
}

← Transactions Locations →