Create Business Customer

Create a Business Customer

Create a Business customer with its registered details, business profile, addresses, and legal identifiers.

Endpoint

POST /api/v2/customers

Customer type

Business

Field	Type	Description or accepted values	Description or accepted values
`name`	String	Required	Registered name of the Business. Must not be blank.
`registeredCountry`	Country enum	Required	Country where the Business is registered, such as `NG` or `US`.
`registrationType`	String	Required	Business registration type. See the supported values in the Business customer types section.
`dateOfRegistration`	Date	Required	Registration date in `YYYY-MM-DD` format.
`category`	Category enum	Required	Business category. When supplied, `industry` must belong to the selected category.
`industry`	Industry enum	Required/Conditional	Business industry. When category is supplied, a valid industry for that `category` should also be supplied.
`registeredAddress`	Address object	Required	Registered legal address.
`officeAddress`	Address object	Required	Primary operating address.
`phoneNumber`	Phone object	Required	Business phone number, country code, and country.
`email`	String	Optional	Business email address.
`website`	String	Optional	Business website.
`description`	String	Required	Description of the Business.
`legalIdentifier`	LegalIdentifier array	Required	Registration, tax, or other legal identifiers. identifierType is required for every supplied item.
`metadata`	String map	Optional	References or attributes maintained by your platform.

Required fields: name and registeredCountry are required by the current customer contract. Additional fields may be required by the compliance rules configured for your program.

Category and Industry

If category is omitted, industry can also be omitted.

If category is supplied, the selected industry should be valid for that category.

Category	Accepted industries
`Agriculture`	`AgriculturalCooperatives, AgriculturalServices`
`Commerce`	`Automobiles, DigitalGoods, PhysicalGoods, RealEstate, DigitalServices, LegalServices, PhysicalServices, ProfessionalServices, OtherProfessionalServices`
`Education`	`NurserySchools, PrimarySchools, SecondarySchools, TertiaryInstitutions, VocationalTraining, VirtualLearning, OtherEducationalServices`
`Gaming`	`Betting, Lotteries, PredictionServices`
`FinancialServices`	`FinancialCooperatives, CorporateServices, PaymentSolutionServiceProviders, Insurance, Investments, AgriculturalInvestments, Lending, BillPayments, Payroll, Remittances, Savings, MobileWallets`
`Health`	`Gyms, Hospitals, Pharmacies, HerbalMedicine, Telemedicine, MedicalLaboratories`
`Hospitality`	`Hotels, Restaurants`
`Nonprofits`	`ProfessionalAssociations, GovernmentAgencies, NGOs, PoliticalParties, ReligiousOrganizations, Leisure_And_Entertainment, Cinemas, Nightclubs, Events, Press_And_Media, RecreationCentres, StreamingServices`
`Logistics`	`CourierServices, FreightServices`
`Travel`	`Airlines, RideSharing, TourServices, Transportation, TravelAgencies`
`Utilities`	`CableTelevision, Electricity, GarbageDisposal, Internet, Telecoms, Water`

Nested Business fields

Object	Field	Requirement	Description or accepted values
`phoneNumber`	`phoneNumber`	Required when object is supplied	National phone number.
`phoneNumber`	`countryCode`	Conditionally required	Dialling code used when `country` is omitted.
`phoneNumber`	`country`	Conditionally required	Required when `countryCode` is not supplied. `Country` enum value. May be derived from countryCode.
	`verified`	Response field	Indicates whether the phone number has been verified.

Address

registeredAddress and officeAddress can contain:

Field	Requirement	Description
`line1`	Optional	Main address line.
`line2`	Optional	Additional address line.
`street`	Optional	Street name.
`city`	Optional	City.
`state`	Optional	State or region.
`postalCode`	Optional	Postal or ZIP code.
`country`	Optional	Country code. A supplied registered-address country e.g. `NG` or `US`.
`addressType`	Not required	The containing field determines the address type (`REGISTERED` or `OFFICE`).

legalIdentifier

Each supplied legal identifier can contain:

Field	Requirement	Description
`identifierType`	Required when an item is supplied	Type of legal identifier.
`number`	Optional in the API contract	Registration or tax identifier value.
`issuingCountry`	Optional	Country that issued the identifier.

Supported legal identifier types include:

Identifier type	Description
`REGISTRATION_NUMBER`	Business registration number.
`TIN`	Tax identification number.
`NATIONAL_BUSINESS_NUMBER`	National business identifier.
`EMPLOYER_IDENTIFICATION_NUMBER`	Employer identification number.
`VAT_REGISTRATION_NUMBER`	Value-added tax registration number.
`GST_REGISTRATION_NUMBER`	Goods and services tax registration number.
`LEGAL_ENTITY_IDENTIFIER`	Legal Entity Identifier issued under the LEI system.

Sample Request Payload to create a business customer

curl --request POST "https://api.getanchor.co/api/v2/customers" \
  --header "x-anchor-key: $ANCHOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "type": "Business",
      "attributes": {
        "name": "Example Industries Ltd",
        "category": "Commerce",
        "industry": "OtherProfessionalServices",
        "phoneNumber": {
          "phoneNumber": "8012345672",
          "countryCode": "234",
          "country": "NG"
        },
        "registeredCountry": "NG",
        "registrationType": "Private_Incorporated",
        "dateOfRegistration": "1999-01-01",
        "registeredAddress": {
          "line1": "1 Example House",
          "line2": "Off Admiralty Way",
          "city": "Lekki",
          "state": "Lagos",
          "postalCode": "23401",
          "country": "NG"
        },
        "officeAddress": {
          "line1": "5 Office Plaza",
          "city": "Lagos",
          "state": "Lagos",
          "postalCode": "23401",
          "country": "NG"
        },
        "description": "Business description",
        "email": "[email protected]",
        "website": "https://example.com",
        "accountUsages": [
          "operatingExpenses",
          "supplierPayments"
        ],
        "legalIdentifier": [
          {
            "identifierType": "REGISTRATION_NUMBER",
            "number": "RC12345678",
            "issuingCountry": "NG"
          },
          {
            "identifierType": "TIN",
            "number": "TIN00998877",
            "issuingCountry": "NG"
          }
        ],
        "metadata": {
          "internalCustomerId": "biz_0001"
        }
      }
    }
  }'

{
  "data": {
    "id": "178880217663338-anc_bus_cst",
    "type": "Business",
    "attributes": {
      "website": "http://ep.website.com",
      "metadata": {
        "internalRef": "biz-0001"
      },
      "isRoot": false,
      "description": "Building computer transistors forever",
      "dateOfRegistration": "1999-01-01",
      "industry": "OtherProfessionalServices",
      "registeredCountry": "NG",
      "legalIdentifier": [
        {
          "identifierType": "REGISTRATION_NUMBER",
          "number": "RC12345678",
          "issuingCountry": "NG"
        },
        {
          "identifierType": "TIN",
          "number": "TIN00998877",
          "issuingCountry": "NG"
        }
      ],
      "officeAddress": {
        "line1": "5 Office Plaza",
        "line2": "Victoria Island",
        "city": "Lekki",
        "state": "Lagos",
        "postalCode": "23401",
        "country": "NG"
      },
      "registeredAddress": {
        "line1": "1 Blaise House",
        "line2": "Off Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "postalCode": "23401",
        "country": "NG"
      },
      "phoneNumber": {
        "phoneNumber": "8034875672",
        "countryCode": "234",
        "country": "NG",
        "verified": false,
        "fullPhoneNumber": "2348034875672"
      },
      "registrationType": "Private_Incorporated",
      "name": "Emeagwali Industries",
      "category": "Commerce",
      "email": "[email protected]",
      "status": "ACTIVE"
    },
    "relationships": {
      "addresses": {
        "data": [
          {
            "id": "178880217663334-anc_addr",
            "type": "Address"
          },
          {
            "id": "178880217663335-anc_addr",
            "type": "Address"
          }
        ]
      },
      "legalIdentifiers": {
        "data": [
          {
            "id": "178880217663344-anc_id_num",
            "type": "LegalIdentifier"
          },
          {
            "id": "178880217663445-anc_id_num",
            "type": "LegalIdentifier"
          }
        ]
      },
      "termsAgreements": {
        "data": []
      },
      "phoneNumbers": {
        "data": [
          {
            "id": "178880217663325-anc_phone",
            "type": "PhoneNumber"
          }
        ]
      }
    }
  }
}

Create Associated Individuals

An Individual customer is created separately for each director, owner, controlling person, or other associated person required by your program. This is slightly different from the standalone Individual Customer onboarding flow. For a Business customer, the Individual represents a person who is associated with the Business.

Associated people are always represented as Individuals, including where ownership passes through another business or legal arrangement. After creating the Individual, link them to the Business using the Business Officer endpoint.

If the person already exists as an Individual in your organization, use the existing customer instead of creating a duplicate.

Create an Individual for a Business

Endpoint

POST /api/v2/customers

Customer type

Individual

Fields

Field	Type	Requirement	Description or accepted values
`legalName`	Name object	Required	Person's legal name. The object accepts `firstName,` `middleName`, `lastName`, and `otherName`.
`dateOfBirth`	Date	Required	`YYYY-MM-DD`. The Individual must be at least 18 years old.
`nationality`	Country enum	Required	Person's country of nationality.
`email`	String	Required	Person's email address.
`gender`	Gender enum	Optional	`Male, Female,` or `Others.`
`isPep`	Boolean	Optional	Whether the person is identified as a politically exposed person.
`occupation`	String	Optional	Person's occupation.
`placeOfWork`	String	Optional	Person's place of work.
`salary`	Number	Optional	Person's salary. The expected currency is USD.
`phoneNumber`	Phone object	Optional	Person's phone number, country code, and country.
`residentialAddress`	Address object	Optional	Person's residential address.
`identifications`	Identification array	Optional	`idNumber` and `idType` are required for every supplied identification.
`nextOfKins`	NextOfKin array	Optional	Next-of-kin relationships supplied with the Individual.
`selfie`	Base64 string	Optional	Must contain a valid Base64-encoded image when supplied.
`metadata`	String map	Optional	References or attributes maintained by your platform.

nextOfKins

nextOfKins is an array of objects, allowing more than one next-of-kin to be provided.

Each object may contain:

Field	Type	Requirement	Description
`name`	Name object	Required when next-of-kin details are supplied	Next-of-kin's name.
`email`	String	Optional	Next-of-kin's email address.
`relationship`	String	Optional	Relationship to the Individual, such as `Sister`, `Brother`, `Spouse`, or another applicable relationship.
`phone / phoneNumber`	Phone object	Optional	Next-of-kin's phone number and country information.

The name object can contain:

firstName
middleName
lastName
otherName

Create individual Customer - Sample request

curl --request POST "https://api.getanchor.co/api/v2/customers" \
  --header "x-anchor-key: $ANCHOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "type": "Individual",
      "attributes": {
        "legalName": {
          "firstName": "Ada",
          "middleName": "Grace",
          "lastName": "Lovelace"
        },
        "gender": "Female",
        "nationality": "NG",
        "dateOfBirth": "1990-01-01",
        "isPep": false,
        "occupation": "Chief Executive Officer",
        "placeOfWork": "Example Industries",
        "salary": 100000,
        "email": "[email protected]",
        "phoneNumber": {
          "phoneNumber": "8012345678",
          "countryCode": "234",
          "country": "NG"
        },
        "residentialAddress": {
          "line1": "1 Example Close",
          "city": "Lekki",
          "state": "Lagos",
          "postalCode": "23401",
          "country": "NG"
        },
        "identifications": [
          {
            "idNumber": "12345678901",
            "idType": "BVN",
            "issuingCountry": "NG"
          }
        ],
        "nextOfKins": [
          {
            "name": {
              "firstName": "Ada",
              "middleName": "Smith",
              "lastName": "Lovelace"
            },
            "email": "[email protected]",
            "relationship": "Sister",
            "phone": {
              "phoneNumber": "8022345680",
              "countryCode": "234",
              "country": "NG"
            }
          }
        ]
      }
    }
  }'

{
  "data": {
    "id": "17771489588010-anc_ind_cst",
    "type": "Individual",
    "attributes": {
      "gender": "Female",
      "verificationDetail": {
        "status": "UNVERIFIED",
        "tier": null
      },
      "fullName": "Lovelace Ada Grace",
      "dateOfBirth": "1990-01-01",
      "countryOfResidence": "NG",
      "isPep": false,
      "occupation": "Engineer",
      "salary": 500000,
      "legalName": {
        "firstName": "Ada",
        "lastName": "Lovelace",
        "middleName": "Grace"
      },
      "phoneNumber": "2348012345678",
      "nationality": "NG",
      "residentialAddress": {
        "line1": "Ada house",
        "line2": "Ada house",
        "city": "Lekki",
        "state": "Lagos",
        "postalCode": "23401",
        "country": "NG"
      },
      "otherName": "Doe",
      "contacts": {
        "email": "[email protected]"
      },
      "status": "ACTIVE"
    },
    "relationships": {
      "addresses": {
        "data": [
          {
            "id": "17771489588030-anc_addr",
            "type": "Address"
          }
        ]
      },
      "identificationNumbers": {
        "data": [
          {
            "id": "17771489588040-anc_id_num",
            "type": "IdentificationNumber"
          }
        ]
      },
      "phoneNumbers": {
        "data": [
          {
            "id": "17771489588030-anc_phone",
            "type": "PhoneNumber"
          }
        ]
      },
      "emailContact": {
        "data": {
          "id": "17771489588020-anc_ctc_det",
          "type": "ContactDetails"
        }
      }
    }
  }
}

Identification type enum

Supported identification types include:

DRIVERS_LICENSE, VOTERS_CARD, PASSPORT, NATIONAL_ID, NIN_SLIP, TAX_ID, BVN, SSNIT, ALIEN_ID, SSN, CPF, CNIC, SMART_ID, CIN, SIN, NIDA, NIN_UK, RESIDENCE_PERMIT

For each supplied identification:

Field	Requirement	Description
`idNumber`	Required	Identification number.
`idType`	Required	Identification type.
`issuingCountry`	Optional	Country that issued the identification.
`issuingDate`	Conditional	Date the identification was issued.
`expiryDate`	Conditional	Date the identification expires.

If expiryDate is supplied, issuingDate must also be supplied.

Link an Individual to the Business

After creating or retrieving the Individual, create a Business Officer relationship to link the Individual to the Business. Create an Officer relationship for each associated Individual. The relationship records the person's role, relationship to the Business, and ownership percentage where applicable.

Endpoint

POST /api/v2/business-officers

Field or relationship	Type	Requirement	Description or accepted values
`role`	BusinessOfficerType enum	Optional in the API contract	`DIRECTOR` or `OWNER.` Supply it for every usable Officer relationship.
`relationshipToBusiness`	String	Optional	Title or relationship the person has with the Business, e.g., `CEO`.
`percentageOwned`	Decimal	Optional	Percentage of the Business owned by the person.
`person`	Resource relationship	Required	ID of the associated `Individual` customer.
`businessCustomer`	Resource relationship	Required	ID of the `Business` customer.

Request Sample

curl --request POST "https://api.getanchor.co/api/v2/business-officers" \
  --header "x-anchor-key: $ANCHOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "type": "Officer",
      "attributes": {
        "relationshipToBusiness": "CEO and Founder",
        "percentageOwned": 50.0,
        "role": "DIRECTOR"
      },
      "relationships": {
        "person": {
          "data": {
            "id": "17622657122991-anc_ind_cst",
            "type": "Individual"
          }
        },
        "businessCustomer": {
          "data": {
            "id": "17622655406120-anc_bus_cst",
            "type": "Business"
          }
        }
      }
    }
  }'

{
  "data": {
    "id": "17622657124550-anc_bus_off",
    "type": "Officer",
    "attributes": {
      "role": "OWNER",
      "percentOwned": 100,
      "relationshipToBusiness": "CEO"
    },
    "relationships": {
      "addresses": {
        "data": [
          {
            "id": "17622655406130-anc_addr",
            "type": "Address"
          },
          {
            "id": "17622655406131-anc_addr",
            "type": "Address"
          }
        ]
      },
      "person": {
        "data": {
          "id": "17622657122991-anc_ind_cst",
          "type": "Individual"
        }
      },
      "termsAgreements": {
        "data": []
      },
      "businessCustomer": {
        "data": {
          "id": "17622655406120-anc_bus_cst",
          "type": "Business"
        }
      },
      "phoneNumbers": {
        "data": [
          {
            "id": "17622655406130-anc_phone",
            "type": "PhoneNumber"
          }
        ]
      },
      "officers": {
        "data": [
          {
            "id": "17622657124550-anc_bus_off",
            "type": "Officer"
          }
        ]
      }
    }
  }
}

Anchor currently supports the Officer roles DIRECTOR and OWNER.