🙋Create a Business for a Customer

Create a Business for a pre-existing Customer. You are also able to complete a CIPC verification on the Business as well as Customer Record.

POST {{baseUrl}}/businesses

Request Body

Name	Type	Description
name*	String	The registered Business name.
type*	String	The type of company the Business is legally registered as. Types of companies accepted: Private Company, Sole Proprietor, Public Company, Closed Corporation, Partnership, NGO, and Business Trust.
reg*	String	The Business Registration Number. Example: xxxx / xxxxxx / xx
enterprise-num*	String	The Business Enterprise Number. Example: Kxxxxxxxxxx
customerId*	String	The UUID for a specific customer that gets generated and returned in the POST Create New Customer response. It ensures that the Business is associated to a specific customer.
cipc_check	Boolean	The CIPC check is an additional feature that would need to be enabled and would come at an additional charge.
popi*	Boolean	This is used to store whether the Business has given you Consent under the Protection Of Personal Information (POPI) Act to continue with collecting their data and performing additional verifications in Gathr.

Suggested entries for Registration Number and Enterprise Number

Company/Business Type	Registration Number	Enterprise Number
Private Company	Company Registration Number	Company Registration Number
Public Company	Company Registration Number	Company Registration Number
Sole Proprietor	Customer ID Number	Unique Company Identifier
Closed Corporation	Company Registration Number	Company Registration Number
Partnership	RSA ID Number of one of the directors	Unique Company Identifier / Customer UUID
Business Trust	Business Trust Number	Unique Company Identifier
NGO	Company Registration Number	Company Registration Number

Example 1 - Request without CIPC check

{
    "customer_id": "{{customerId}}",
    "name": "Finch Technologies (Pty) Ltd",
    "type": "Private Company",
    "reg": "2015/123456/23",
    "enterprise_num":"K2016513771",
    "popi": true
}

Example 2 - Request with CIPC check

{
    "customer_id": "{{customerId}}",
    "name": "Finch Technologies (Pty) Ltd",
    "type": "Private Company",
    "reg": "2015/123456/23",
    "enterprise_num": "K2016513771", 
    "cipc_check":true,
    "popi": true
}

API Responses

201 - Created

Business Created for a Customer - Without CIPC

{
    "data": {
        "id": "{{businessId}}",
        "name": "FINCH TECHNOLOGIES",
        "type": "Private Company",
        "reg": "2015/255566/07",
        "enterprise_num": "K201525556607",
        "linked_customers": [
            {
                "customer": "{{customerId}}",
                "relationship": "director"
            }
        ],
        "cipc_business_verified": false,
        "cipc_director_verified": false,
        "cipc_information": null,
        "cipc_timestamp": null
    }
}

Business Created for a Customer - With CIPC - Director & Business Verified

{
    "data": {
        "id": "c1ceecf6-3835-41d5-ba75-686acd64e021",
        "name": "FINCH TECHNOLOGIES",
        "type": "Private Company",
        "reg": "2015/255566/07",
        "enterprise_num": "K201525556607",
        "linked_customers": [
            {
                "customer": "ddb8a2c9-b846-412a-a2d3-3dcb077229e7",
                "relationship": "director"
            }
        ],
        "cipc_business_verified": true,
        "cipc_director_verified": true,
        "cipc_information": {
            "CIPCEnterprises": [
                {
                    "RegistrationNumber": "201525556607",
                    "EnterpriseNumber": "K2015/255566/07",
                    "EnterpriseName": "FINCH TECHNOLOGIES",
                    "ShortName": "",
                    "RegistrationDate_OnFile": "28072015",
                    "BusinessStartDate_OnFile": "28072015",
                    "StatusCode": "03",
                    "StatusDate": "",
                    "Status": "In Business",
                    "Sic_Code": "",
                    "Sic_Code_Description": "BUSINESS ACTIVITIES NOT RESTRICTED.",
                    "FinancialYearEnd": 2,
                    "FinancialYearEnd_EffectiveDate": "",
                    "PhysicalAddressLine1": "8 MELVILLE ROAD",
                    "PhysicalAddressLine2": "ILLOVO",
                    "PhysicalAddressLine3": "GAUTENG",
                    "PhysicalAddressLine4": "",
                    "PhysicalAddressPostCode": "2196",
                    "PostalAddressLine1": "PO BOX 5675",
                    "PostalAddressLine2": "WALMER",
                    "PostalAddressLine3": "PORT ELIZABETH",
                    "PostalAddressLine4": "",
                    "PostalAddressPostCode": "6070",
                    "CountryCode": "ZA",
                    "TaxNumber": "9005229258",
                    "RegistrationDate": "2015-07-28",
                    "BusinessStartDate": "2015-07-28",
                    "RecordDate": "2023-09-29",
                    "Source": "CIPC",
                    "Reference": "",
                    "CompanyTypeCode": "07",
                    "CompanyType": "Private Company",
                    "ChangeTypeCode": "",
                    "ChangeType": "",
                    "TelephoneNumber": []
                }
            ],
            "EnterpriseTotalRecords": 1,
            "EnterpriseTotalReturnedRecords": 0,
            "enterprise_request_reference": "d8ece408-92c6-4f66-984a-410fcb2003ec",
            "CIPCDirectors": [
                {
                    "IDNumber": "{{IDNumber}}",
                    "IDNumberTen": {{IdNumberTen}},
                    "RegistrationNumber": "201525556607",
                    "CompanyName": "FINCH TECHNOLOGIES",
                    "CompanyStatus": "03",
                    "CompanyType": "Private Company",
                    "CompanySize": "SME",
                    "DirectorStatusCode": "A",
                    "DirectorStatus": "Active",
                    "MaxStatusDate": "2019-04-25",
                    "PersonName": "{{FullName}}",
                    "ResignationDate": "None",
                    "AppointmentDate": "2019-04-25",
                    "ValidID": true,
                    "IDNameMatch": "",
                    "Source": "CIPC",
                    "Reference": "",
                    "UsingExtraPersonDetails": false,
                    "IsTreasuryRestrictedSupplier": "",
                    "DirectorTypeCode": "D",
                    "DirectorType": "Director",
                    "Country": ""
                },
                {
                    "IDNumber": "{{IDNumber}}",
                    "IDNumberTen": {{IdNumberTen}},
                    "RegistrationNumber": "201525556607",
                    "CompanyName": "FINCH TECHNOLOGIES",
                    "CompanyStatus": "03",
                    "CompanyType": "Private Company",
                    "CompanySize": "SME",
                    "DirectorStatusCode": "C",
                    "DirectorStatus": "Resigned",
                    "MaxStatusDate": "2018-08-31",
                    "PersonName": "{{FullName}}",
                    "ResignationDate": "2018-08-31",
                    "AppointmentDate": "2015-07-28",
                    "ValidID": true,
                    "IDNameMatch": "",
                    "Source": "CIPC",
                    "Reference": "",
                    "UsingExtraPersonDetails": false,
                    "IsTreasuryRestrictedSupplier": "",
                    "DirectorTypeCode": "D",
                    "DirectorType": "Director",
                    "Country": ""
                },
                {
                    "IDNumber": "{{IDNumber}}",
                    "IDNumberTen": "{{IdNumberTen}}",
                    "RegistrationNumber": "201525556607",
                    "CompanyName": "FINCH TECHNOLOGIES",
                    "CompanyStatus": "03",
                    "CompanyType": "Private Company",
                    "CompanySize": "SME",
                    "DirectorStatusCode": "A",
                    "DirectorStatus": "Active",
                    "MaxStatusDate": "2015-07-28",
                    "PersonName": "{{FullName}} ",
                    "ResignationDate": "None",
                    "AppointmentDate": "2015-07-28",
                    "ValidID": true,
                    "IDNameMatch": "",
                    "Source": "CIPC",
                    "Reference": "",
                    "UsingExtraPersonDetails": false,
                    "IsTreasuryRestrictedSupplier": "",
                    "DirectorTypeCode": "D",
                    "DirectorType": "Director",
                    "Country": ""
                },
                {
                    "IDNumber": "{{IDNumber}}",
                    "IDNumberTen": {{IdNumberTen}},
                    "RegistrationNumber": "201525556607",
                    "CompanyName": "FINCH TECHNOLOGIES",
                    "CompanyStatus": "03",
                    "CompanyType": "Private Company",
                    "CompanySize": "SME",
                    "DirectorStatusCode": "A",
                    "DirectorStatus": "Active",
                    "MaxStatusDate": "2015-07-28",
                    "PersonName": "{{FullName}} ",
                    "ResignationDate": "None",
                    "AppointmentDate": "2015-07-28",
                    "ValidID": true,
                    "IDNameMatch": "",
                    "Source": "CIPC",
                    "Reference": "",
                    "UsingExtraPersonDetails": false,
                    "IsTreasuryRestrictedSupplier": "",
                    "DirectorTypeCode": "D",
                    "DirectorType": "Director",
                    "Country": ""
                },
                {
                    "IDNumber": "{{IDNumber}}",
                    "IDNumberTen": {{IdNumberTen}},
                    "RegistrationNumber": "201525556607",
                    "CompanyName": "FINCH TECHNOLOGIES",
                    "CompanyStatus": "03",
                    "CompanyType": "Private Company",
                    "CompanySize": "SME",
                    "DirectorStatusCode": "A",
                    "DirectorStatus": "Active",
                    "MaxStatusDate": "2015-07-28",
                    "PersonName": "{{FullName}} ",
                    "ResignationDate": "None",
                    "AppointmentDate": "2015-07-28",
                    "ValidID": true,
                    "IDNameMatch": "",
                    "Source": "CIPC",
                    "Reference": "",
                    "UsingExtraPersonDetails": false,
                    "IsTreasuryRestrictedSupplier": "",
                    "DirectorTypeCode": "D",
                    "DirectorType": "Director",
                    "Country": ""
                },
                {
                    "IDNumber": "{{IDNumber}}",
                    "IDNumberTen": {{IdNumberTen}},
                    "RegistrationNumber": "201525556607",
                    "CompanyName": "FINCH TECHNOLOGIES",
                    "CompanyStatus": "03",
                    "CompanyType": "Private Company",
                    "CompanySize": "SME",
                    "DirectorStatusCode": "A",
                    "DirectorStatus": "Active",
                    "MaxStatusDate": "2015-07-28",
                    "PersonName": "{{FullName}} ",
                    "ResignationDate": "None",
                    "AppointmentDate": "2015-07-28",
                    "ValidID": true,
                    "IDNameMatch": "",
                    "Source": "CIPC",
                    "Reference": "",
                    "UsingExtraPersonDetails": false,
                    "IsTreasuryRestrictedSupplier": "",
                    "DirectorTypeCode": "D",
                    "DirectorType": "Director",
                    "Country": ""
                }
            ],
            "DirectorTotalRecords": 5,
            "DirectorTotalReturnedRecords": 6,
            "director_request_reference": "cf04e101-5dd5-4a60-a966-6d95dcd355c3"
        },
        "cipc_timestamp": "2024-08-14T11:48:24.545918Z"
    }
}

403 - Forbidden

CIPC module not enabled on tenant

{
    "errors": {
        "error": "CIPC checks are not enabled for your tenant. Please contact support if you wish to enable the feature."
    }
}

409 - Conflict

Business Not Unique

{
    "errors": "Business not unique"
}

422 - Unprocessable Content

Input Validation - Registration Number

{
    "errors": {
        "reg": [
            "The reg field is required."
        ]
    }
}

{
    "errors": {
        "reg": [
            "Expected registration number xxxx/xxxxxx/xx or customer id number"
        ]
    }
}

Input Validation - Enterprise Number

{
    "errors": {
        "enterprise_num": [
            "The enterprise num field is required."
        ]
    }
}

{
    "errors": {
        "enterprise_num": [
            "Expected enterprise number K/B/Mxxxxxxxxxxxx or guid v4"
        ]
    }
}

Input Validation - Business Type

{
    "errors": {
        "type": [
            "The accepted Business types include Private Company, Sole Proprietor, Public Company, Closed Corporation, Partnership, NGO, Business Trust"
        ]
    }
}