Create an Identity

Create an Identity for your Buyer, Recipient, or Seller, using identity_roles and type to indicate the type of Identity you're creating.

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:
required
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.
required
object

The underwriting details required to verify Identities.

identity_roles
Array of strings

The sets of permissions available to the Identity.

Items Enum: "APPLICATION_OWNER" "BENEFICIAL_OWNER" "BUYER" "PLATFORM_OWNER" "RECIPIENT" … 2 more
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. (For example, order_number: 25, item_type: produce, department: sales)
type
string

The identity type.

Value: "BUSINESS"
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 the previously created Identities.


For details on how to query endpoints using the available parameters, see Query Parameters.      


Request 
query Parameters
after_cursor
string
Return every resource created after the cursor value.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
limit
integer
The numbers of items to return.


 
 Example:  limit=10
id
string
Filter by id.


 
created_at.gte
string <date-time> 
Filter where created_at is after the given date.


 
 Example:  created_at.gte=2022-09-27T11:21:23
created_at.lte
string <date-time> 
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.


 
 Example:  default_statement_descriptor=Finix%20Flowers
business_name
string
Filter by the full business name. Partial business names are not supported.


 
 Example:  business_name=Finix%20Flowers
business_type
string
Filter by the business type. Partial business types are not supported.


 Enum: "INDIVIDUAL_SOLE_PROPRIETORSHIP" "CORPORATION" "LIMITED_LIABILITY_COMPANY" "PARTNERSHIP" "LIMITED_PARTNERSHIP" … 6 more 
 Example:  business_type=INDIVIDUAL_SOLE_PROPRIETORSHIP
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=John
last_name
string
Filter by the last name of the person associated to the Identity.


 
 Example:  last_name=Smith
title
string
Filter by the title if available.


 
 Example:  title=ceo
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
tags.key
string
Filter by the tag's key. For more information, see Tags.


 
 Example:  tags.key=card_type
tags.value
string
Filter by the tag's value. For more information, see Tags.


 
 Example:  tags.value=business_card
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
Response schema and example when fetching a Payment Instrument.


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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
Responses 
200
Response schema and example when fetching a Payment Instrument.


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
Any of:
required
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.
    • 



 
required
object
The underwriting details required to verify Identities.


 
identity_roles
Array of strings
The sets of permissions available to the Identity.


Items Enum: "APPLICATION_OWNER" "BENEFICIAL_OWNER" "BUYER" "PLATFORM_OWNER" "RECIPIENT" … 2 more 
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.
(For example, order_number: 25, item_type: produce, department: sales)
    • 



 
type
string
The identity type.


 Value: "BUSINESS"  
Responses 
201
Single Associated 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 
Response samples 
application/json
{}
List Associated Identities
Retrieve a list of Associated Identities for an Identity.


For details on how to query endpoints using the available parameters, see Query Parameters.      


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.


 
 Example:  after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor
string
Return every resource created before the cursor value.


 
 Example:  before_cursor=TRnasXQ5AmjsLnPMwnme7TL4
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
{}