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
header Parameters
Accept
string
Default: application/hal+json
Finix-Version
string
Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01
Request Body schema: application/json
Any of:
object or null
  • Additional underwriting details required to verify Identities.
  • Required for any Merchants onboarded by Finix Flex customers. If you have any questions, please contact Finix Support.
object

The underwriting details required to verify Identities.

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/json
{}
List Identities
Retrieve a list of Identities.


Request 
query Parameters
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.


 
tags.key
string
Filter by the key of a Tag.


 
tags.value
string
Filter by the value of a Tag.


 
header Parameters
Accept
string
 Default:  application/hal+json
Body Header


 
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/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Request Body schema: application/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.


 
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/json" \
  -H "Finix-Version: 2022-02-01" \
  -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/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
Request Body schema: application/json
object
Underwriting data that's required to verify the Identity.


 
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/json" \
  -H "Finix-Version: 2022-02-01" \
  -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": "14158885080", 
        "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/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.


 
header Parameters
Accept
string
 Default:  application/hal+json
 
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 "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/json
{}