Create an Identity

Create an Identity for your seller or buyer.

All fields for a buyer's Identity are optional.

Providing business_type indicates that the Identity is being created for a Merchant.

Related Guides: Getting Started, Onboarding

Request
Request Body schema: application/hal+json
Any of:
object or null

Addition underwriting details required to verify Identities.

object

The underwriting details required to verify Identities.

tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
201

Single Identity object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

post/identities
Request samples
Response samples
application/hal+json
{}

List Identities

Retrieves a list of Identities.

Request
query Parameters
sort
string

Specify key to be used for sorting the collection.

after_cursor
string

Return every resource created after the cursor value.

limit
integer

The numbers of items to return.

Example: limit=10
id
string

Filter by id.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=2022-09-27T11:21:23
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=2022-09-27T11:21:23
default_statement_descriptor
string

Filter by the default_statement_descriptor.

business_name
string

Filter by the full business name. Partial business names are not supported.

business_type
string

Filter by the business type. Partial business types are not supported.

email
string

Filter by the email address or email domain. Partial emails are not supported.

Example: email=user@example.org
first_name
string

Filter by the first name of the person associated to the Identity.

Example: first_name=Daphne
last_name
string

Filter by the last name of the person associated to the Identity.

Example: last_name=kline
title
string

Filter by the title if available.

Example: title=ceo
before_cursor
string

Return every resource created before the cursor value.

Responses
200

List of Identity objects

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/identities
Request samples
curl https://finix.sandbox-payments-api.com/identities \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Fetch an Identity

Retrieve the details of a previously created Identity.

Request
path Parameters
identity_id
required
string

ID of the Identity to fetch.

Responses
200

Single Identity object

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/identities/{identity_id}
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Update an Identity

Update an existing Identity.

If you are updating the Identity of a Merchant that’s already been onboarded, you need to verify the merchant again.

Request
path Parameters
identity_id
required
string

ID of the Identity to fetch.

Request Body schema: application/hal+json
Any of:
object

Additional underwriting data that's required to verify the Identity of merchants.

object

Underwriting data that's required to verify the Identity.

tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
200

Single Identity object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/identities/{identity_id}
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDrH4G2VTfNjn1VFkvhcyMYj \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '
  {
    "entity": {
      "email": "user@example.org",
      "first_name": "John",
      "last_name": "Smith",
      "phone": "7145677613"
    }
  }'
Response samples
application/hal+json
{}

Create an Associated Identity

Create an associated Identity for every owner with 25% or more ownership over the merchant.

Request
path Parameters
identity_id
required
string

ID of Identity to associate object with.

Request Body schema: application/hal+json
object

Underwriting data that's required to verify the Identity.

tags
object or null

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500.

(e.g., order number: 25, item_type: produce, department: sales, etc.)

Responses
201

Single Identity object

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/identities/{identity_id}/associated_identities
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
  -d '
{
    "entity": {
        "first_name": "John", 
        "last_name": "Smith", 
        "title": "Founder", 
        "dob": {
            "month": 1, 
            "day": 1, 
            "year": 2013
        }, 
        "principal_percentage_ownership": 25, 
        "phone": "1234567890", 
        "personal_address": {
            "city": "San Francisco", 
            "region": "CA", 
            "postal_code": "90650", 
            "line1": "123 Main Street", 
            "country": "USA"
        }, 
        "email": "john.smith@company1.com", 
        "tax_id": "123456789"
    }
}'
Response samples
application/hal+json
{}

List Associated Identities

Retrieve a list of Associated Identities for an Identity.

Request
path Parameters
identity_id
required
string

ID of Identity to associate object with.

query Parameters
limit
integer <int64>

The number of entries to return.

after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

Responses
200

List of Identity objects

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/identities/{identity_id}/associated_identities
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities \
  -H "Content-Type: application/vnd.api+json" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}