LinkCy

Consumer

The consumer represents the individual partner client. It must have a valid phone number and be formally identified with a KYC procedure before carrying out any operation.

List consumers

Fetch all your consumer end-users. More options will be added in the near future.

SecurityLinkcy-Auth
Request
query Parameters
sortAttribute
string
Enum: "UPDATE_DATE" "LAST_NAME" "CREATION_DATE"
lastName
string
phone
string
emailAddress
string
kycStatus
Array of strings
Items Enum: "NOT_STARTED" "CREATED" "PROCESSING" "ABORTED" "PENDING_REVIEW" … 2 more
bankingStatus
Array of strings
Items Enum: "VALIDATED" "PENDING" "MISSING_DATA" "BLOCKED" "NOT_CREATED"
suspensionStatus
Array of strings
Items Enum: "SUSPENDED" "NOT_SUSPENDED"
linkcyStatus
Array of strings
Items Enum: "PENDING" "FORBIDDEN" "MISSING_DATA" "VALIDATED" "CLOSING" … 1 more
complianceStatus
Array of strings
Items Enum: "PENDING" "DECLINED" "PENDING_REVIEW" "VALIDATED"
overallStatus
string
Enum: "ACTIVE" "INACTIVE"
pageSize
integer <int32> <= 100

The size of the page to be returned.

page
integer <int32> >= 0

The page number.

sortDirection
string
Enum: "ASC" "DESC"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

get/api/partner/consumers
Request samples 
Response samples 
application/json
{
  • "content": [
    ],
  • "totalElements": 1,
  • "page": 0,
  • "pageSize": 0
}
Create a consumer
This is the first step to create an Individual consumer. Phone object is mandatory to be able to go on to the next steps. You can add optional fields, this will help us to manage compliance triggers.


Only a few pieces of information are asked here, most of it will be extracted from documents during the KYC process. By doing the Endpoint: Get Consumer information, you will get access to all data.


You cannot create two consumers with the same phone number. Phone numbers must be unique.


SecurityNone or Linkcy-Auth 
Request 
Request Body schema: application/json
required
partnerName
string
The partnerName, mandatory if you create a consumer as anonymous. Ignored if requesting as a partner.


 
firstName
string
The first name of the user to create. Must only contains Latin-1 characters.


 
middleName
string
The middle name of the user to create. Must only contains Latin-1 characters.


 
lastName
string
The last name of the user to create. Must only contains Latin-1 characters.


 
externalId
string  [ 0 .. 511 ] characters 
A unique identifier that you can use to link this consumer to a user in your system.


 
required
object (PhoneRequestDto) 
 
object (EuropeanAddressRequest) 
 
emailAddress
string
 
sourceOfFunds
string
 Enum: "COMPENSATION_PAYOUT" "COMPANY_PROFITS" "COMPANY_SALE" "DIVIDEND_PAYMENTS" "DIVORCE_SETTLEMENT" … 11 more 
otherSourceOfFunds
string  [ 0 .. 511 ] characters 
Description of source of funds if 'OTHER' was chosen.


 
occupation
string
The consumer usual or principal work or business as a means of earning a living.


 Enum: "BUSINESS_OWNER" "CLERGY" "CRAFTSMAN" "ENGINEER" "EXECUTIVE" … 12 more 
otherOccupation
string  [ 0 .. 511 ] characters 
Description of occupation if 'OTHER' was chosen.


 
lastTermsAccepted
string
The version of the terms and conditions signed by the consumer.


 
taxIdentificationNumber
string  [ 0 .. 255 ] characters 
 
taxCountry
string
 Enum: "AUT" "BEL" "BGR" "CHE" "CYP" … 28 more 
accountPurposes
Array of strings  unique 
Items Enum: "PAY_BILLS" "MONEY_TO_FROM_FAMILY" "DIVIDENDS" "SAVINGS" "PERSONAL_BUSINESS_PURPOSES" … 8 more 
object (ExpectedMonthlyExpenses) 
 
object (Metadata) 
A custom field to save data.


This field's size is limited to 3000 characters.


 
Responses 
201
Created


400
Bad Request


401
Unauthorized


403
Forbidden


409
Conflict


post/api/partner/consumers
Request samples 
application/json
{
  • "partnerName": "string",
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "externalId": "string",
  • "phone": {
    },
  • "address": {
    },
  • "emailAddress": "string",
  • "sourceOfFunds": "COMPENSATION_PAYOUT",
  • "otherSourceOfFunds": "string",
  • "occupation": "BUSINESS_OWNER",
  • "otherOccupation": "string",
  • "lastTermsAccepted": "1.0",
  • "taxIdentificationNumber": "string",
  • "taxCountry": "AUT",
  • "accountPurposes": [
    ],
  • "expectedMonthlyExpenses": {
    },
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Get consumer's information
Get all information about one consumer by only using his consumer ID. You will get access to all verification statuses.


SecurityLinkcy-Auth 
Request 
path Parameters
consumerId
required
string <uuid> 
 
Responses 
200
OK


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


get/api/partner/consumers/{consumerId}
Request samples 
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "externalId": "string",
  • "phone": {
    },
  • "kycInfo": {
    },
  • "status": {
    },
  • "termsAccepted": true,
  • "address": {
    },
  • "firstName": "string",
  • "middleName": "string",
  • "lastName": "string",
  • "email": {
    },
  • "gender": "MALE",
  • "birthCity": "string",
  • "birthIsoCountryCode": "ABW",
  • "birthDate": "2019-08-24",
  • "sourceOfFunds": "COMPENSATION_PAYOUT",
  • "otherSourceOfFunds": "string",
  • "occupation": "BUSINESS_OWNER",
  • "otherOccupation": "string",
  • "notes": "string",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "updateDate": "2019-08-24T14:15:22Z",
  • "strongAuthentication": {
    },
  • "taxIdentificationNumber": "string",
  • "taxCountry": "ABW",
  • "accountPurposes": [
    ],
  • "expectedMonthlyExpenses": {
    },
  • "partnerMetadata": { },
  • "userMetadata": { }
}
Update a consumer
You can patch a consumer to update some information. Depending on the information patched, you will have to perform another action:


    

  • External ID -> no action to perform
    

    • 

  • Phone -> you will need to use Endpoint POST Send consumer verification code & validate consumer phone
    

    • 

  • Address : we will use our tools to check if the address is valid or not, we recommend you to ask your consumer to confirm the address once the modification is done. Address is very important to send cards. Once the card is activated, the address status will go from valid to verified.
    

    • 

  • Email address -> The "emailAddressVerified" status will switch to "false" you will need to use Endpoint POST Send a verification email to the consumer to verify the email address. 
    

    • 

  • Source of funds -> no action to perform
    

    • 

  • Occupation -> no action to perform
    

    • 

  • Terms & Condition -> Needed if "termsAccepted" is "false".
    

    • 



This operation might require SCA.


SecurityLinkcy-Auth 
Request 
path Parameters
consumerId
required
string <uuid> 
 
header Parameters
Linkcy-SCA-Strategy
string
 Default:  PUSH_NOTIFICATION
The strategy to use when a SCA is required:



More information:


    

  • PUSH_NOTIFICATION: will send a notification if the SCA is required.
    • 

  • JOIN_CODE: will return a join code if SCA is required.
    • 

  • FAIL: will fail if SCA is required.
    • 

  • BY_PASS: Sandbox only - will ignore any SCA if used.




ErrorCode


    

  • 409 Conflict
      

    • SCA_REQUIRED: The operation requires SCA. Can be returned if you try to use BY_PASS while not allowed. Will be returned if strategy is FAIL.
      • 

    • SCA_DEVICE_NOT_SET: The operation requires SCA and strategy allows it, but the user has no sca device set up. You need to enroll one first. 





 Enum: "PUSH_NOTIFICATION" "JOIN_CODE" "FAIL" "BY_PASS"  
Linkcy-SCA-Factor
string
 Default:  BIOMETRY
The factor type required for the operation :



More information:


    

  • BIOMETRY: will require fingerprint or face recognition depending on device.
    • 

  • PIN: will require the endpoint pin. When using this factor, a pin must have been registered through the SDK first. Sca pin and end user password can differ.




ErrorCode


    

  • 400 Bad Request
      

    • SCA_FACTOR_NOT_SET: The user has a sca device set up, but the factor requested is not enrolled yet. You must either enroll it or change the factor.





 Enum: "BIOMETRY" "PIN"  
Linkcy-SCA-Id
string <uuid> 
The id of the completed SCA operation.



ErrorCode


    

  • 404 Not Found
      

    • SCA_INTERACTION_NOT_FOUND: The specified id could not be found.
      • 

    

    • 

  • 409 Conflict
      

    • SCA_INTERACTION_NOT_COMPLETED: The SCA interaction is not completed (pending).
      • 

    • SCA_INTERACTION_DECLINED: The SCA interaction was declined by user or expired. 
      • 

    • SCA_INTERACTION_ALREADY_CONSUMED: The SCA interaction has already been used, you need to create a new one.
      • 

    • SCA_INTERACTION_DOES_NOT_MATCH: The SCA interaction does not match the one you are trying to make. Body or url is different.





 
Request Body schema: application/json
required
externalId
string  [ 0 .. 511 ] characters 
A unique identifier that you can use to link this consumer to a user in your system.


 
object (EuropeanAddressRequest) 
Address that will be used on the bank statements of your users.


 
emailAddress
string
 
sourceOfFunds
string
 Enum: "COMPENSATION_PAYOUT" "COMPANY_PROFITS" "COMPANY_SALE" "DIVIDEND_PAYMENTS" "DIVORCE_SETTLEMENT" … 11 more 
otherSourceOfFunds
string  [ 0 .. 511 ] characters 
Description of source of funds if 'OTHER' was chosen.


 
occupation
string
The consumer usual or principal work or business as a means of earning a living.


 Enum: "BUSINESS_OWNER" "CLERGY" "CRAFTSMAN" "ENGINEER" "EXECUTIVE" … 12 more 
otherOccupation
string  [ 0 .. 511 ] characters 
Description of occupation if 'OTHER' was chosen.


 
lastTermsAccepted
string
The version of the terms and conditions signed by the consumer.


 
taxIdentificationNumber
string  [ 0 .. 255 ] characters 
 
taxCountry
string
 Enum: "AUT" "BEL" "BGR" "CHE" "CYP" … 28 more 
accountPurposes
Array of strings  unique 
Items Enum: "PAY_BILLS" "MONEY_TO_FROM_FAMILY" "DIVIDENDS" "SAVINGS" "PERSONAL_BUSINESS_PURPOSES" … 8 more 
object (ExpectedMonthlyExpenses) 
 
object (PhoneRequestDto_Partner) 
Update the phone of this corporate related person. Note: if you wish to change the phone of an account owner, please contact us.


 
object (Metadata) 
 Deprecated 
Use userMetadata or partnerMetadata instead.


 
object (User metadata) 
A custom field to save data.


This field's size is limited to 3000 characters.


 
object (Partner metadata) 
A custom field to save data that cannot be modified by the end-user.


This field's size is limited to 3000 characters.


Note: if you are authenticated as end-user, trying to update this field will result in a Forbidden Error.


 
Responses 
200
OK


202
Waiting SCA


400
Bad Request


401
Unauthorized


403
Forbidden


404
Not Found


patch/api/partner/consumers/{consumerId}
Request samples 
application/json
{
  • "externalId": "string",
  • "address": {
    },
  • "emailAddress": "string",
  • "sourceOfFunds": "COMPENSATION_PAYOUT",
  • "otherSourceOfFunds": "string",
  • "occupation": "BUSINESS_OWNER",
  • "otherOccupation": "string",
  • "lastTermsAccepted": "1.0",
  • "taxIdentificationNumber": "string",
  • "taxCountry": "AUT",
  • "accountPurposes": [
    ],
  • "expectedMonthlyExpenses": {
    },
  • "phone": {
    },
  • "metadata": {
    },
  • "userMetadata": {
    },
  • "partnerMetadata": {
    }
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "updateDate": "2019-08-24T14:15:22Z"
}
➔ Next to Corporate