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

The server understood the request but could not process it.

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
The server understood the request but could not process it.


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
The server understood the request but could not process it.


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
{}