Weavr
Powered by Redocly

Consumers

Consumers are identities representing individuals. Once on-boarded, Consumers can create and manage their own instruments via your application.

Create a consumer

Create a Consumer Identity to represent an Individual.

The information provided must be accurate as it will be passed on for KYC verification with our partner.

Incorrect information may incur a re-processing fee.

Securityapi_key
Request
header Parameters
idempotency-ref
string

A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

Request Body schema: application/json
required
profileId
required
string (ProfileId) ^[0-9]+$

The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

tag
string (Tag) <= 50 characters ^[a-zA-Z0-9_-]+$

The tag field is a custom field that can be used to search and filter.

required
object

The root user represents the identity.

Root users need to verify their email address and mobile number, as well as complete KYC, as part of the Consumer's due diligence process.

ipAddress
required
string [ 5 .. 45 ] characters

The IP address of the user doing the registration.

acceptedTerms
required
boolean

Must be set to true to indicate that the consumer has accepted the terms and conditions.

baseCurrency
string (Currency) = 3 characters ^[A-Z]*$

The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

feeGroup
string

The fee group which the consumer is bound to. Fee groups provide the possibility of different fees to users under the same profile. If fee groups are not required, ignore this field.

sourceOfFunds
string (ConsumerSourceOfFunds)
Deprecated

The consumer's source of funds.

Enum: "PERSONAL_SAVINGS" "FAMILY_SAVINGS" "LABOUR_CONTRACT" "CIVIL_CONTRACT" "RENT" "FUNDS_FROM_OTHER_AUXILIARY_SOURCES" "SALE_OF_MOVABLE_ASSETS" "SALE_OF_REAL_ESTATE" "ORDINARY_BUSINESS_ACTIVITY" "DIVIDENDS" "LOAN_FROM_FINANCIAL_INSTITUTIONS_CREDIT_UNIONS" "LOAN_FROM_THIRD_PARTIES" "INHERITANCE" "SALE_OF_COMPANY_SHARES_BUSINESS" "OTHER"
sourceOfFundsOther
string
Deprecated

Description of source of funds in case OTHER was chosen.

Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/consumers
Request samples
application/json
{
  • "profileId": "string",
  • "tag": "string",
  • "rootUser": {
    },
  • "ipAddress": "string",
  • "acceptedTerms": true,
  • "baseCurrency": "str",
  • "feeGroup": "string",
  • "sourceOfFunds": "PERSONAL_SAVINGS",
  • "sourceOfFundsOther": "string"
}
Response samples
application/json
{
  • "id": {
    },
  • "profileId": "string",
  • "tag": "string",
  • "rootUser": {
    },
  • "creationTimestamp": 0,
  • "ipAddress": "string",
  • "acceptedTerms": true,
  • "baseCurrency": "str",
  • "feeGroup": "string",
  • "sourceOfFunds": "PERSONAL_SAVINGS",
  • "sourceOfFundsOther": "string"
}

Get a consumer

Retrieve the details of the logged-in Consumer.

Securityauth_token and api_key
Responses
200

Success

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/consumers
Request samples 
Response samples 
application/json
{
  • "id": {
    },
  • "profileId": "string",
  • "tag": "string",
  • "rootUser": {
    },
  • "creationTimestamp": 0,
  • "ipAddress": "string",
  • "acceptedTerms": true,
  • "baseCurrency": "str",
  • "feeGroup": "string",
  • "sourceOfFunds": "PERSONAL_SAVINGS",
  • "sourceOfFundsOther": "string"
}
Update a consumer
Update the details of the logged-in consumer identity.


If the Consumer root user has already completed KYC, the following details cannot be updated:


    

  • name
    • 

  • surname
    • 

  • email
    • 

  • mobile Country Code
    • 

  • mobile Number
    • 

  • date of Birth
    • 

  • address
    • 



Securityauth_token and api_key 
Request 
Request Body schema: application/json
required
tag
string (Tag)   <= 50 characters ^[a-zA-Z0-9_-]+$
The tag field is a custom field that can be used to search and filter.


 
name
string  <= 20 characters ^[^0-9~!@#$%^*()_+={}\\|:;,<>/?]*$
The first name of the Consumer root user.


 
surname
string  <= 20 characters ^[^0-9~!@#$%^*()_+={}\\|:;,<>/?]*$
The last name of the Consumer root user.


 
email
string <email>  (Email) 
E-mail Address of the user


 
object (Mobile) 
 
object (Date) 
Date of birth of the consumer root user.


 
object (AddressWithCountryRequired) 
Address of the consumer root user.


 
feeGroup
string
The fee group which the consumer will be bound to. Do not specify this if you are not using fee groups.


 
baseCurrency
string (Currency)   = 3 characters ^[A-Z]*$
The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.


 
occupation
string (Occupation) 
 Deprecated 
The industry of the identity.


 Enum: "ACCOUNTING" "AUDIT" "FINANCE" "PUBLIC_SECTOR_ADMINISTRATION" "ART_ENTERTAINMENT" "AUTO_AVIATION" "BANKING_LENDING" "BUSINESS_CONSULTANCY_LEGAL" "CONSTRUCTION_REPAIR" "EDUCATION_PROFESSIONAL_SERVICES" "INFORMATIONAL_TECHNOLOGIES" "TOBACCO_ALCOHOL" "GAMING_GAMBLING" "MEDICAL_SERVICES" "MANUFACTURING" "PR_MARKETING" "PRECIOUS_GOODS_JEWELRY" "NON_GOVERNMENTAL_ORGANIZATION" "INSURANCE_SECURITY" "RETAIL_WHOLESALE" "TRAVEL_TOURISM" "FREELANCER" "STUDENT" "UNEMPLOYED" "RETIRED" "OTHER"  
sourceOfFunds
string (ConsumerSourceOfFunds) 
 Deprecated 
The consumer's source of funds.


 Enum: "PERSONAL_SAVINGS" "FAMILY_SAVINGS" "LABOUR_CONTRACT" "CIVIL_CONTRACT" "RENT" "FUNDS_FROM_OTHER_AUXILIARY_SOURCES" "SALE_OF_MOVABLE_ASSETS" "SALE_OF_REAL_ESTATE" "ORDINARY_BUSINESS_ACTIVITY" "DIVIDENDS" "LOAN_FROM_FINANCIAL_INSTITUTIONS_CREDIT_UNIONS" "LOAN_FROM_THIRD_PARTIES" "INHERITANCE" "SALE_OF_COMPANY_SHARES_BUSINESS" "OTHER"  
sourceOfFundsOther
string
 Deprecated 
Description of source of funds in case OTHER was chosen.


 
placeOfBirth
string
The place of birth of the consumer root user.


 
nationality
string (Nationality)   = 2 characters ^[A-Z]+$
Nationality of the consumer root user, in ISO 3166 alpha-2 format.


 
resetMobileCounter
boolean
 
userTag
string (Tag)   <= 50 characters ^[a-zA-Z0-9_-]+$
The tag to be assigned to the root user.


 
Responses 
200
Success


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


409
Conflict


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


patch/consumers
Request samples 
application/json
{
  • "tag": "string",
  • "name": "string",
  • "surname": "string",
  • "email": "user@example.com",
  • "mobile": {
    },
  • "dateOfBirth": {
    },
  • "address": {
    },
  • "feeGroup": "string",
  • "baseCurrency": "str",
  • "occupation": "ACCOUNTING",
  • "sourceOfFunds": "PERSONAL_SAVINGS",
  • "sourceOfFundsOther": "string",
  • "placeOfBirth": "string",
  • "nationality": "st",
  • "resetMobileCounter": true,
  • "userTag": "string"
}
Response samples 
application/json
{
  • "id": {
    },
  • "profileId": "string",
  • "tag": "string",
  • "rootUser": {
    },
  • "creationTimestamp": 0,
  • "ipAddress": "string",
  • "acceptedTerms": true,
  • "baseCurrency": "str",
  • "feeGroup": "string",
  • "sourceOfFunds": "PERSONAL_SAVINGS",
  • "sourceOfFundsOther": "string"
}
Send an email verification code to the root user
The first step in verifying a root user's email. The root user whose email address is to be verified is sent an email containing a randomly generated code.


This code must then be provided in the consumerRootUserEmailVerify operation to verify the root user's email address.


Note that on the Sandbox Environment, the verificationCode is always set to "123456".


Securityapi_key 
Request 
Request Body schema: application/json
required
email
required
string <email>  (Email) 
E-mail Address of the user


 
Responses 
204
Success - No Content.


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


409
Conflict


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


post/consumers/verification/email/send
Request samples 
application/json
{
  • "email": "user@example.com"
}
Response samples 
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}
Verify email of the root user
The second step in verifying the root user's email. The randomly generated code sent to the root user via
email, using the consumerRootUserEmailVerificationCodeSend operation, is submitted here to verify the root user's email.


This is needed as part of the verification process for basic due diligence.


Note that on the Sandbox Environment, emails are not sent and the verification code is always set to "123456".


Securityapi_key 
Request 
Request Body schema: application/json
required
email
required
string <email>  (Email) 
E-mail Address of the user


 
verificationCode
required
string (VerificationCode)   = 6 characters ^[0-9]+$
A randomly generated one-time use code used to verify the user's email address or mobile number.


 
Responses 
204
Success - No Content.


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


409
Conflict


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


post/consumers/verification/email/verify
Request samples 
application/json
{
  • "email": "user@example.com",
  • "verificationCode": "string"
}
Response samples 
application/json
{
  • "message": "string",
  • "syntaxErrors": {
    }
}
Start KYC for a consumer
Consumers need to complete due diligence (KYC) before they can create instruments and fund transaction.


This operation initiates the due diligence process for the logged-in consumer. 


The level of KYC that will be required from the user can be provided as an optional parameter - if this is not provided, KYC_LEVEL_2 will be assumed. 


Due Diligence is handled by a KYC provider, you will need to embed the KYC UI Component in your application to show the KYC screens to your users.


To initialise the KYC UI Component, you need a reference that is given to you in the response of this operation.


Securityauth_token and api_key 
Request 
Request Body schema: application/json
kycLevel
string (KycLevel) 
The KYC level that the consumer will be assigned to, which determines the due diligence details that the user will need to provide.


 Enum: "KYC_LEVEL_1" "KYC_LEVEL_2"  
Array of objects
List of KYC details to be prefilled for the consumer.


 
Responses 
200
Success


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


409
Conflict


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


post/consumers/kyc
Request samples 
application/json
{
  • "kycLevel": "KYC_LEVEL_1",
  • "prefillDetails": [
    ]
}
Response samples 
application/json
{
  • "reference": "string",
  • "kycLevel": "KYC_LEVEL_1"
}
Get KYC for a consumer
Returns the KYC status for the logged-in consumer.


Securityauth_token and api_key 
Responses 
200
Success


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


get/consumers/kyc
Request samples 
Response samples 
application/json
{
  • "fullDueDiligence": "NOT_STARTED",
  • "kycLevel": "KYC_LEVEL_1",
  • "ongoingFullDueDiligence": "NOT_STARTED",
  • "ongoingKycLevel": "KYC_LEVEL_1"
}
Start consumer KYC on mobile
Consumers need to complete due diligence (KYC) before they can create instruments and perform transactions.
Use this call instead of /consumers/kyc only in case where the KYC is to be performed using a mobile device.
The level of KYC that will be required from the user can be provided as an optional parameter - if this is not 
provided, KYC_LEVEL_2 will be assumed. 
The information returned in the response is to be used to integrate directly with Sumsub Mobile SDK.


Securityauth_token and api_key 
Request 
Request Body schema: application/json
kycLevel
string (KycLevel) 
The KYC level that the consumer will be assigned to, which determines the due diligence details that the user will need to provide.


 Enum: "KYC_LEVEL_1" "KYC_LEVEL_2"  
Array of objects
List of KYC details to be prefilled for the consumer.


 
Responses 
200
Success


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


409
Conflict


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


post/consumers/kyc_mobile_sumsub
Request samples 
application/json
{
  • "kycLevel": "KYC_LEVEL_1",
  • "prefillDetails": [
    ]
}
Response samples 
application/json
{
  • "verificationFlow": "string",
  • "accessToken": "string",
  • "identityType": "string",
  • "externalUserId": "string",
  • "kycProviderKey": "string",
  • "kycLevel": "KYC_LEVEL_1"
}
Charge fee to a consumer
Charge a fee to the logged-in consumer based on a pre-defined custom fee. Custom fees can be configured in the Multi Portal.


The fees collected will be deposited into your Revenue Account. The balance and transaction history of your revenue account can be viewed in the Multi Portal.


Securityauth_token and api_key 
Request 
header Parameters
idempotency-ref
string
A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.


 
Request Body schema: application/json
required
feeType
required
string
The fee type as defined in the Multi Portal.


 
required
object (InstrumentId) 
The instrument from where the fee should be deducted.


 
Responses 
200
Success


400
Bad Request Error - Your request is invalid.


401
Unauthorized - Your credentials or access token are invalid.


403
Forbidden - Access to the requested resource or action is forbidden.


409
Conflict


429
Too many requests.


500
Internal Server Error - There is a problem with the server. Please try again later.


503
Service Unavailable - We're temporarily offline for maintenance. Please try again later.


default
Error


post/consumers/fees/charge
Request samples 
application/json
{
  • "feeType": "string",
  • "source": {
    }
}
Response samples 
application/json
{
  • "transactionId": {
    },
  • "profileId": "string",
  • "feeType": "string",
  • "source": {
    },
  • "availableBalanceAdjustment": {
    },
  • "state": "INITIALISED",
  • "creationTimestamp": 0
}
➔ Next to Authorised Users