CIPC API

https://guide.cipc.co.za
Admin
The CIPC API provides public access to digitally recorded company, cooperative, and intellectual...
Tokens:9,334
Snippets:44
Trust Score:9.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### HTTP Example: Get Supporting Documents Request

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/supporting-documents

An example HTTP GET request to retrieve supporting documents using the entity statement ID. Replace 'YOUR_API_KEY' with your actual subscription key.

```HTTP
GET /sandbox/boreg/register/files/{entitystatementid} HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Accept: */*
```

--------------------------------

### Example HTTP Request for Ownership Control

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/ownership-or-control-statement

An example HTTP GET request demonstrating how to query the ownership-control API endpoint. This snippet includes the necessary Host and Ocp-Apim-Subscription-Key headers for authentication.

```HTTP
GET /sandbox/boreg/ownership-control/{statementid} HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Accept: */*
```

--------------------------------

### HTTP Request Example: Get Basic Company Information

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/information

An example HTTP POST request demonstrating how to query the /enterprise/v1/information endpoint to retrieve company details using an enterprise number.

```HTTP
POST /enterprise/v1/information HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "enterprise_number": "2020/939681/07"
}
```

--------------------------------

### HTTP Request Example: Get Individual Document

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/individual-document

Example HTTP GET request to retrieve a supporting document by its ID, including required headers like Host and Ocp-Apim-Subscription-Key.

```HTTP
GET /sandbox/boreg/files/{documentid} HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Accept: */*
```

--------------------------------

### HTTP Request Example: Get Beneficial Ownership

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/entity-statement

An example HTTP/1.1 request demonstrating how to call the beneficial ownership API endpoint, including required headers like Host and Ocp-Apim-Subscription-Key.

```HTTP
GET /sandbox/boreg/enterprise/register/{enterprise_number} HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Accept: */*

```

--------------------------------

### HTTP Request Example: Get Person Details

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/natural-person-statement

An example of an HTTP GET request to the /sandbox/boreg/person-details/{statementid} endpoint, demonstrating the required headers including the subscription key.

```HTTP
GET /sandbox/boreg/person-details/{statementid} HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Accept: */*
```

--------------------------------

### Example 404 Not Found Response for Entity Statement API

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/entity-statement

A JSON response example indicating that the requested resource was not found.

```JSON
{
"statusCode": 404,
"message": "Resource Not Found."
}
```

--------------------------------

### Example JSON Response for Ownership Control

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/ownership-or-control-statement

A sample JSON response illustrating the data structure returned by a successful GET request to the ownership-control API. It provides concrete examples of multiple ownership statements, including details like statement ID, type, interests, and publication dates.

```JSON
{
  "ownership": [
    {
      "statementid": 97,
      "statementtype": "OwnershipOrControlStatement",
      "describedbypersonstatement": 76,
      "describedbyentitystatement": 4,
      "created_on": "2023-04-14T16:19:00.0000000+00:00",
      "interests": [
        {
          "interest_type": "Shareholding/Beneficial Ownership",
          "share": 17,
          "voting_rights": 0
        }
      ],
      "publication_details": [
        {
          "effective_date": "0001-01-01"
        }
      ],
      "modified_on": "2023-10-13T14:08:21.0000000+00:00"
    },
    {
      "statementid": 98,
      "statementtype": "OwnershipOrControlStatement",
      "describedbypersonstatement": 77,
      "describedbyentitystatement": 4,
      "created_on": "2023-04-14T16:23:39.0000000+00:00",
      "interests": [
        {
          "interest_type": "Trustee of a trust",
          "share": 0,
          "voting_rights": 0
        }
      ],
      "publication_details": [
        {
          "effective_date": "2018-01-10"
        }
      ],
      "modified_on": "2023-10-13T14:06:45.0000000+00:00"
    },
    {
      "statementid": 99,
      "statementtype": "OwnershipOrControlStatement",
      "describedbypersonstatement": 78,
      "describedbyentitystatement": 4,
      "created_on": "2023-04-14T16:30:45.0000000+00:00",
      "interests": [
        {
          "interest_type": "Shareholding/Beneficial Ownership",
          "share": 46,
          "voting_rights": 0
        }
      ],
      "publication_details": [
        {
          "effective_date": "0001-01-01"
        }
      ],
      "modified_on": "2023-10-13T14:09:15.0000000+00:00"
    }
  ],
  "links": [
    {
      "rel": "collection",
      "href": "/ownership-control/"
    }
  ]
}
```

--------------------------------

### Example JSON Response for Company Profile (200 OK)

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/companyprofile

A comprehensive sample JSON response structure returned by the Get Company Profile API endpoint upon a successful 200 OK request, illustrating the detailed company data available.

```JSON
{
  "Company": [
    {
      "enterprise_number": "string",
      "enterprise_name": "string",
      "enterprise_short_name": "string",
      "trading_name": "string",
      "translated_name": "string",
      "enterprise_type_description": "string",
      "business_activity": "string",
      "registration_date": "string",
      "business_start_date": "string",
      "enterprise_status_description": "string",
      "financial_year_end": "string",
      "financial_year_effective_date": "string",
      "tax_number": "string",
      "office_address": [
        {
          "address_line_1": "string",
          "address_line_2": "string",
          "city": "string",
          "region": "string",
          "country": "string",
          "postal_code": "string"
        }
      ],
      "postal_address": [
        {
          "address_line_1": "string",
          "address_line_2": "string",
          "city": "string",
          "region": "string",
          "postal_code": "string",
          "country": "string"
        }
      ],
      "directors": [
        {
          "first_names": "string",
          "surname": "string",
          "initials": "string",
          "date_of_birth": "string",
          "director_status": "string",
          "director_type": "string",
          "designation": "string",
          "appointment_date": "string",
          "resignation_date": "string",
          "member_size_interest": 0,
          "member_contribution": 0,
          "residential_address_1": "string",
          "residential_address_2": "string",
          "residential_address_3": "string",
          "residential_address_4": "string",
          "residential_postal_code": "string",
          "country": "string"
        }
      ],
      "secretaries": [],
      "auditors": [],
      "captial": [
        {
          "capital_type_descr": "string",
          "cap_no_shares": 0,
          "cap_par": 0,
          "cap_amt_share": 0,
          "cap_prem": 0
        }
      ],
      "history": [
        {
          "change_date": "string",
          "change_description": "string"
        }
      ]
    }
  ]
}
```

--------------------------------

### API Reference: Get Supporting Documents by Entity Statement ID

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/supporting-documents

Provides a detailed reference for the GET /register/files/{entitystatementid} API endpoint, including its purpose, parameters, authorization requirements, and possible responses with their schemas and an example.

```APIDOC
Endpoint: GET https://cipc-apm-rs-dev.azure-api.net/sandbox/boreg/register/files/{entitystatementid}
Description: Get supporting document by entity statement id

Authorizations:
  - apiKeyHeader (in header)
  - apiKeyQuery (in query parameter)

Path Parameters:
  - entitystatementid:
      Type: integer
      Description: Entity Id of the registered beneficial ownership registration
      Required: true
      Possible values: 4

Responses:
  - 200 Success:
      Content-Type: application/json
      Schema:
        type: object
        properties:
          documents:
            type: array
            items:
              type: object
              properties:
                bodocumentationid: {type: integer, description: "Unique ID for the document"}
                boregid: {type: integer, description: "Beneficial ownership registration ID"}
                referencenumber: {type: string, description: "Reference number for the document"}
                contenttype: {type: string, description: "MIME type of the document (e.g., application/pdf)"}
                createddate: {type: string, format: "date-time", description: "Date and time the document was created"}
                documenttypedesc: {type: string, description: "Description of the document type (e.g., OTHER)"}
                documentstatusdesc: {type: string, description: "Status of the document (e.g., ACTIVE)"}
                documentname: {type: string, description: "Name of the document file"}
          links:
            type: array
            items:
              type: object
              properties:
                rel: {type: string, description: "Relationship of the link (e.g., collection)"}
                href: {type: string, description: "URL of the related resource"}
      Example:
        {
          "documents": [
            {
              "bodocumentationid": 242,
              "boregid": 4,
              "referencenumber": "60000707734",
              "contenttype": "application/pdf",
              "createddate": "2023-04-15T21:44:19.0000000+00:00",
              "documenttypedesc": "OTHER",
              "documentstatusdesc": "ACTIVE",
              "documentname": "COR14.3 (1).pdf"
            },
            {
              "bodocumentationid": 362,
              "boregid": 4,
              "referencenumber": "60000709767",
              "contenttype": "application/pdf",
              "createddate": "2023-04-25T09:05:57.0000000+00:00",
              "documenttypedesc": "OTHER",
              "documentstatusdesc": "ACTIVE",
              "documentname": "Welcome Letter.pdf"
            },
            {
              "bodocumentationid": 387,
              "boregid": 4,
              "referencenumber": "60000710168",
              "contenttype": "application/pdf",
              "createddate": "2023-04-26T14:22:26.0000000+00:00",
              "documenttypedesc": "OTHER",
              "documentstatusdesc": "ACTIVE",
              "documentname": "beb12ca9-c3a6-4be4-a1c5-4fab975b5fda (1).pdf"
            },
            {
              "bodocumentationid": 563,
              "boregid": 4,
              "referencenumber": "60000712633",
              "contenttype": "application/pdf",
              "createddate": "2023-05-11T09:35:38.0000000+00:00",
              "documenttypedesc": "OTHER",
              "documentstatusdesc": "ACTIVE",
              "documentname": "2022-09-16 - CoR39 (BR Address accepted but not changed).pdf"
            },
            {
              "bodocumentationid": 346,
              "boregid": 4,
              "referencenumber": "60000709681",
              "contenttype": "application/pdf",
              "createddate": "2023-04-24T16:12:14.0000000+00:00",
              "documenttypedesc": "OTHER",
              "documentstatusdesc": "ACTIVE",
              "documentname": "Share certificate.pdf"
            }
          ],
          "links": [
            {
              "rel": "collection",
              "href": "/register/files/"
            }
          ]
        }
  - 401 Unauthorised:
      Content-Type: application/json
  - 404 Resource Not Found
```

--------------------------------

### HTTP Example: POST Request to Retrieve Company Directors

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/directors

An example HTTP request demonstrating how to call the /enterprise/v1/directors endpoint. It includes necessary headers like Ocp-Apim-Subscription-Key and the JSON request body with the enterprise_number.

```HTTP
POST /enterprise/v1/directors HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "enterprise_number": "string"
}
```

--------------------------------

### HTTP Request Example for Employee Verification

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/employee-verification

Illustrates a sample HTTP POST request to the employee verification endpoint. It includes the host, required API subscription key, content type, and a JSON body containing the identity number for verification.

```HTTP
POST /enterprise/v1/employee-verification HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "identity_number": "8205305555555"
}
```

--------------------------------

### Send POST Request to Get Company Profile (HTTP)

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/companyprofile

Example HTTP/1.1 request to the CIPC Company Profile API, demonstrating how to include the API key and request body for retrieving company information.

```HTTP
POST /enterprise/v1/companyprofile HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "enterprise_number": "2020/939681/07"
}
```

--------------------------------

### Example: HTTP POST Request for Filing History

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/filing-history

A sample HTTP POST request demonstrating how to call the /enterprise/v1/filing-history endpoint. It includes the host, API key header, content type, and the JSON request body with the 'enterprise_number'.

```HTTP
POST /enterprise/v1/filing-history HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "enterprise_number": "string"
}
```

--------------------------------

### Example HTTP POST Request for Registered Office Address

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/registered-office-address

An example of an HTTP POST request to the registered office address API endpoint, showing the host, required API key header, content type, and the JSON request body with the enterprise number.

```HTTP
POST /enterprise/v1/registered-office-address HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "enterprise_number": "string"
}
```

--------------------------------

### Example 200 OK Response for Entity Statement API

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/entity-statement

A successful JSON response example for the Entity Statement API, showing the structure of the 'register' array with enterprise details (statementid, type, creation date, reference number, legal entity type, company type, enterprise name, status, registration date, total shares, identifiers, publication details) and 'links' array.

```JSON
{
    "register": [
        {
            "statementid": 4,
            "statementtype": "entityStatement",
            "created_on": "2023-04-03",
            "reference_number": "60000705245",
            "legal_entity_type": "Private Company",
            "company_type": "NON-AFFECTED COMPANY WITH BENEFICIAL OWNERSHIP",
            "enterprise_name": "CIPC LTD",
            "status": "Complete",
            "registration_date": "2013-10-06",
            "total_shares": 46,
            "identifiers": [
                {
                    "registration authority": "ZA-CIPC",
                    "enterprise_number": "2013/187505/07"
                }
            ],
            "publication_details": [
                {
                    "publisher_id": "CIP123",
                    "publisher": "Sello Ndhlovu",
                    "publication_date": "2023-03-31"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "collection",
            "href": "../enterprise/register/"
        }
    ]
}
```

--------------------------------

### API Endpoint: Get Ownership or Control Statement by ID

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/ownership-or-control-statement

Detailed API documentation for the GET /ownership-control/{statementid} endpoint. This section outlines the endpoint's purpose, required authorization methods, path parameters with their types and descriptions, and various possible HTTP responses including success and error codes with their respective content types and schema examples.

```APIDOC
Endpoint: GET https://cipc-apm-rs-dev.azure-api.net/sandbox/boreg/ownership-control/{statementid}
Description: Get ownership or control statement by statement Id.

Authorizations:
  - apiKeyHeader
  - apiKeyHeaderapiKeyQuery

Path Parameters:
  - statementid:
    Type: integer
    Required: Yes
    Description: Ownership or control statement id
    Possible values: `1`

Responses:
  - 200 Success:
    Content-Type: application/json
    Schema: {"ownership":[{"statementid":0,"statementtype":"string","describedbypersonstatement":0,"describedbyentitystatement":0,"created_on":"string","interests":[{"interest_type":"string","share":0,"voting_rights":0}],"publication_details":[{"effective_date":"string"}],"modified_on":"string"}],"links":[{"rel":"string","href":"string"}]}
  - 401 Unauthorised
  - 404 Resource Not Found:
    Content-Type: application/json
```

--------------------------------

### CIPC API Reference Structure

Source: https://guide.cipc.co.za/user-guide

This snippet outlines the hierarchical structure of the CIPC API documentation, detailing the main API categories and their respective endpoints for Companies and Beneficial Ownership data.

```APIDOC
API Documentation:
  Companies API reference:
    - Companyprofile
    - Information
    - Appointments
    - Directors
    - Employee verification
    - Registered office address
    - Filing history
  BO API reference (Beneficial Ownership):
    - Entity statement
    - Ownership or control statement
    - Natural person statement
    - Supporting documents
    - Individual document
```

--------------------------------

### Example 401 Unauthorized Response for Entity Statement API

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/entity-statement

A JSON response example indicating an unauthorized access attempt due to a missing or invalid access token.

```JSON
{
    "statusCode": 401,
    "message": "Unauthorized. Access token is missing or invalid."
}
```

--------------------------------

### HTTP POST Request for Company Director Appointment

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/appointments

An example of an HTTP POST request to retrieve company director appointment details. This snippet demonstrates the necessary headers, including the Ocp-Apim-Subscription-Key, and the JSON body containing the enterprise_number and identity_number.

```HTTP
POST /enterprise/v1/appointments HTTP/1.1
Host: cipc-apm-rs-dev.azure-api.net
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "enterprise_number": "2020/939681/07",
  "identity_number": "8205300000089"
}
```

--------------------------------

### API Specification: Get Basic Company Information

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/information

Defines the POST /enterprise/v1/information endpoint, including its purpose, required parameters, authorization methods, and the detailed schema for a successful response.

```APIDOC
post /enterprise/v1/information
Get basic company information

Authorizations:
  apiKeyHeader
  apiKeyHeaderapiKeyQuery

Body:
  enterprise_number: string (Required) - The company number of the company information to return.

Responses:
  200: Success (application/json)
  401: Unauthorised (application/json)
```

```APIDOC
{
  "type": "string",
  "properties": {
    "Enterprise": {
      "type": "string",
      "items": {
        "type": "string",
        "properties": {
          "enterprise_number": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "enterprise_name": {
            "type": "string"
          },
          "enterprise_type_description": {
            "type": "string"
          },
          "sic_description": {
            "type": "string"
          },
          "registration_date": {
            "type": "string"
          },
          "enterprise_status_description": {
            "type": "string"
          },
          "financial_year_end": {
            "type": "string"
          },
          "financial_year_effective_date": {},
          "physical_address_1": {
            "type": "string"
          },
          "physical_address_2": {
            "type": "string"
          },
          "physical_address_3": {
            "type": "string"
          },
          "physical_address_4": {
            "type": "string"
          },
          "physical_code": {
            "type": "string"
          },
          "postal_address_1": {
            "type": "string"
          },
          "postal_address_2": {
            "type": "string"
          },
          "postal_address_3": {
            "type": "string"
          },
          "postal_address_4": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "tax_number": {
            "type": "string"
          },
          "business_start_date": {
            "type": "string"
          }
        },
        "required": [
          "string"
        ]
      }
    }
  }
}
```

--------------------------------

### API Reference: Get Person Details by Statement ID

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/natural-person-statement

Comprehensive documentation for the GET /person-details/{statementid} endpoint, detailing its purpose, authorization requirements, path parameters, and expected responses.

```APIDOC
Endpoint: GET https://cipc-apm-rs-dev.azure-api.net/sandbox/boreg/person-details/{statementid}
Description: Get the individual person details with significant control by statement Id

Authorizations:
  - apiKeyHeader
  - apiKeyQuery

Path parameters:
  - statementid:
    Type: Integer
    Required: Yes
    Description: Person statement Id
    Possible values: 97

Responses:
  - 200 Success:
    Content-Type: application/json
    Description: Successful retrieval of person details.
    Example Schema: {"persons":[{"statementid":0,"statementtype":"string","is_verified":0,"created_on":"string","describedbyentitystatement":0,"describedbypersonstatement":0,"persontype":"string","nationalities":[{"country_of_birth":"string","code":"string"}],"names":[{"type":"string","full_name":"string","name":"string","last_name":"string"}],"demographic":"string","gender":"string","date_of_birth":"string","country_of_residence":"string","addresses":[{"address_type":"string","address_line_1":"string","address_line_2":"string","city":"string","region":"string","postal_code":"string"}],"modified_on":"string"}],"links":[{"rel":"string","href":"string"}]}
  - 401 Unauthorised:
    Content-Type: application/json
    Description: Authentication failed or invalid API key.
  - 404 Resource Not Found:
    Description: The requested resource could not be found.
```

--------------------------------

### Example: Successful Filing History API Response (200 OK)

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/filing-history

A sample JSON response body for a successful (HTTP 200 OK) call to the filing history API. It shows the structure of the 'filings_history_list' array, including details like 'annual_return_year', 'date_filed', and 'status'.

```JSON
{
  "filings_history_list": [
    {
      "annual_return_year": 2019,
      "annual_return_date": "2019-08-29",
      "non_compliance_date": "2019-08-29",
      "date_filed": "2022-11-21",
      "amount_paid": 100,
      "status": "string"
    }
  ]
}
```

--------------------------------

### Successful Employee Verification API Response JSON

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/employee-verification

Provides a JSON example of a successful response from the employee verification API. It outlines the structure of the `director_list` array, detailing individual director information and associated enterprise details.

```JSON
{
  "director_list": [
    {
      "identity_number": "string",
      "first_names": "string",
      "surname": "string",
      "initials": "string",
      "director_status": "string",
      "role": "string",
      "member_size_interest": 0,
      "member_contribution": 0,
      "appointment_date": "string",
      "resignation_date": "string",
      "enterprise_details": [
        {
          "enterprise_number": "string",
          "enterprise_name": "string",
          "enterprise_type": "string",
          "enterprise_status": "string",
          "registration_date": "string"
        }
      ]
    }
  ]
}
```

--------------------------------

### API Reference: Get Individual Document by ID

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/individual-document

Details the HTTP GET endpoint for retrieving a specific supporting document using its unique ID. Includes endpoint URL, parameters, authorization methods, and possible response codes.

```APIDOC
Endpoint: individual-document
Method: GET
URL: https://cipc-apm-rs-dev.azure-api.net/sandbox/boreg/files/{documentid}
Description: Get supporting document by document id

Authorizations:
  - apiKeyHeader
  - apiKeyHeaderapiKeyQuery

Path Parameters:
  - name: documentid
    type: any
    required: true

Responses:
  - code: 200
    description: Success
  - code: 401
    description: Unauthorised
  - code: 404
    description: Resource Not Found
```

--------------------------------

### API Reference: Get Beneficial Ownership by Enterprise Number

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/entity-statement

This section details the GET endpoint for retrieving beneficial ownership information. It includes path parameters, authorization requirements, and expected response structures for success and error cases.

```APIDOC
GET /sandbox/boreg/enterprise/register/{enterprise_number}

Description: Get beneficial ownership by enterprise number.

Authorizations:
  - apiKeyHeader
  - apiKeyQuery

Path Parameters:
  - enterprise_number (string, Required): Company registration number

Responses:
  - 200 Success (application/json)
    Headers: object
    Response Body Example (Schema): {"register":[{"statementid":0,"statementtype":"string","created_on":"string","reference_number":"string","legal_entity_type":"string","company_type":"string","enterprise_name":"string","status":"string","registration_date":"string","total_shares":0,"identifiers":[{"registration authority":"string","enterprise_number":"string"}],"publication_details":[{"publisher_id":"string","publisher":"string","publication_date":"string"}]}],"links":[{"rel":"string","href":"string"}]}
  - 401 Unauthorised (application/json)
  - 404 Not Found
```

```JSON
{
  "register": [
    {
      "statementid": 4,
      "statementtype": "entityStatement",
      "created_on": "2023-04-03T07:49:37.0000000+00:00",
      "reference_number": "60000705245",
      "legal_entity_type": "Private Company",
      "company_type": "NON-AFFECTED COMPANY WITH BENEFICIAL OWNERSHIP",
      "enterprise_name": "FLUIDROCK GOVERNANCE ACADEMY",
      "status": "BO COMPLETE REGISTRATIONS",
      "registration_date": "2013-09-10",
      "total_shares": 46,
      "identifiers": [
        {
          "registration authority": "ZA-CIPC",
          "enterprise_number": "2013/187505/07"
        }
      ],
      "publication_details": [
        {
          "publisher_id": "AN0790",
          "publisher": "AN0790",
          "publication_date": "2023-03-04"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "collection",
      "href": "/enterprise/register/4"
    }
  ]
}
```

--------------------------------

### Example JSON Response: Successful Person Details Retrieval

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/natural-person-statement

A sample JSON response body for a successful 200 OK request to the person details API, illustrating the structure and typical data for a person's record.

```JSON
{
  "persons": [
    {
      "statementid": 76,
      "statementtype": "personStatement",
      "is_verified": 0,
      "created_on": "14-04-2023",
      "describedbyentitystatement": 4,
      "describedbypersonstatement": 97,
      "persontype": "naturalPerson",
      "nationalities": [
        {
          "country_of_birth": "South Africa",
          "code": "ZA"
        }
      ],
      "names": [
        {
          "type": "individual",
          "full_name": "SHIRLEY DIANE BRAHAM",
          "name": "SHIRLEY DIANE",
          "last_name": "BRAHAM"
        }
      ],
      "demographic": "White",
      "gender": "Female",
          "date_of_birth": "13-04-1964",
      "country_of_residence": "South Africa",
      "addresses": [
        {
          "address_type": "business",
          "address_line_1": "43 BERILLEUM AVENUE",
          "address_line_2": "WILRO PARK",
          "city": "ROODEPOORT",
          "region": "Gauteng",
          "postal_code": "1724"
        },
        {
          "address_type": "postal",
          "address_line_1": "POSTNET SUITE 402",
          "address_line_2": "PRIVATE BAG X033",
          "city": "RIVONIA",
          "region": "Gauteng",
          "postal_code": "2128"
        }
      ],
      "modified_on": "13-10-2023"
    }
  ],
  "links": [
    {
      "rel": "collection",
      "href": "/individual-details/K2013187505/"
    }
  ]
}
```

--------------------------------

### Requesting CIPC API Access Token

Source: https://guide.cipc.co.za/getting-started/authorization

This section demonstrates how to send an HTTP POST request to the `/oauth2/token` endpoint to obtain an access token. It includes examples for raw HTTP and C# HttpClient, showing the required form-urlencoded body parameters like grant_type, client_id, username, password, and scope.

```HTTP
POST /oauth2/token HTTP/1.1
Host: <example.com>
Content-Type: application/x-www-form-urlencoded
Body: {
  "grant_type": password,
  "client_id": "CIPC Client",
  "username": "username",
  "password": "password",
  "scope": "scope"
}
```

```HTTP
POST /oauth20/token HTTP/1.1
Host: <example.com>
Ocp-Apim-Subscription-Key: a11...f1ee
Content-Type: application/x-www-form-urlencoded
Content-Length: 189

grant_type=password&client_id={client_id}&username={username}&password={password}&scope={scope}
```

```C#
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "<example.com>/oauth20/token");
request.Headers.Add("Ocp-Apim-Subscription-Key", "a11f1.....722ee");
var collection = new List<KeyValuePair<string, string>>();
collection.Add(new("grant_type", "password"));
collection.Add(new("client_id", "client_id"));
collection.Add(new("username", "username"));
collection.Add(new("password", "password"));
collection.Add(new("scope", "scope"));
var content = new FormUrlEncodedContent(collection);
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

--------------------------------

### Example JSON Response for Registered Office Address

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/registered-office-address

Illustrates the structure of a successful JSON response (HTTP 200) from the registered office address API, detailing the fields for physical and postal addresses including enterprise number and various address lines.

```JSON
{
  "registered-office-address": [
    {
      "enterprise_number": "string",
      "physical_address_1": "string",
      "physical_address_2": "string",
      "physical_address_3": "string",
      "physical_address_4": "string",
      "physical_code": "string",
      "postal_address_1": "string",
      "postal_address_2": "string",
      "postal_address_3": "string",
      "postal_address_4": "string",
      "postal_code": "string"
    }
  ]
}
```

--------------------------------

### Successful JSON Response for Company Director Appointment

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/appointments

This example illustrates the structure of a successful JSON response (HTTP 200) from the Appointments API. It details the various fields returned for a director's appointment, such as personal details, company information, and dates related to their appointment and resignation.

```APIDOC
{
  "appointment": [
    {
      "first_names": "string",
      "surname": "string",
      "initials": "string",
      "identity_number": "string",
      "date_of_birth": "1997-06-11",
      "director_status": "string",
      "enterprise_number": "string",
      "enterprise_name": "string",
      "director_type": "string",
      "designation": "string",
      "enterprise_type": "string",
      "enterprise_status": "string",
      "registration_date": "27-01-2021",
      "appointment_date": "27-01-2021",
      "resignation_date": "27-01-2023",
      "country_code": "string",
      "member_size_interest": 0,
      "member_contribution": 0,
      "residential_address_1": "string",
      "residential_address_2": "string",
      "residential_address_3": "string",
      "residential_address_4": "string",
      "residential_postal_code": "string"
    }
  ]
}
```

--------------------------------

### Using CIPC API Access Token for Authenticated Requests

Source: https://guide.cipc.co.za/getting-started/authorization

This example demonstrates how to include the acquired access token in subsequent API requests by adding an `Authorization` header with `Bearer` type and the token value. This is required for all authenticated queries.

```HTTP
POST </enterprise/information> HTTP/1.1
Host: <apim.cipc.co.za>
Authorization: Bearer yJ...124nOvc
Content-Type: application/json; charset=utf-8
Body: <...>
```

--------------------------------

### Entity Statement API Request Details and Headers

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/entity-statement

Details the HTTP GET request for retrieving enterprise registration information, including the necessary headers for authentication and content type. The API retrieves registration details based on a provided enterprise number.

```APIDOC
HTTP Method: GET
Endpoint Description: Retrieves the registration details of an enterprise based on the provided enterprise number.

Headers:
  Name: Content-Type
  Value: application/json

  Name: Authorization
  Value: Bearer <token>

  Name: Ocp-Apim-Subscription-Key
  Value: <api key>
```

--------------------------------

### API Reference: Get Company Profile

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/companyprofile

Documents the API endpoint for retrieving a company's profile using its enterprise number. Includes details on the request method, URL, authentication, request body parameters, and possible responses with their schemas.

```APIDOC
Method: POST
Path: /enterprise/v1/companyprofile
Full URL: https://cipc-apm-rs-dev.azure-api.net/enterprise/v1/companyprofile

Description: Get company profile

Authorizations:
  - apiKeyHeader (Header)
  - apiKeyQuery (Query Parameter)

Request Body (application/json):
  Property: enterprise_number
  Type: string
  Description: The company number of the company information to return.
  Required: Yes
  Example: {"enterprise_number": "2020/939681/07"}

Responses:
  200 OK:
    Description: Company Profile
    Content-Type: application/json
    Schema: Object containing a "Company" array with detailed properties.
  401 Unauthorized:
    Description: Unauthorised
    Content-Type: application/json
```

--------------------------------

### API Endpoint Specification: Verify Directors

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/employee-verification

Defines the POST /employee-verification API endpoint, including its purpose, URL, required authorizations, request body parameters (identity number), and expected success (200) and error (401) responses with their respective content types and example structures.

```APIDOC
Verify Directors
post https://cipc-apm-rs-dev.azure-api.net/enterprise/v1/employee-verification
Get details of an individual company director appointment by identity number

Authorizations:
  apiKeyHeader
  apiKeyHeaderapiKeyQuery

Body:
  identity_number: string (Required)

Responses:
  200: Success
    application/json
    Example: {"director_list":[{"identity_number":"string","first_names":"string","surname":"string","initials":"string","director_status":"string","role":"string","member_size_interest":0,"member_contribution":0,"appointment_date":"string","resignation_date":"string","enterprise_details":[{"enterprise_number":"string","enterprise_name":"string","enterprise_type":"string","enterprise_status":"string","registration_date":"string"}]}]}
  401: Unauthorised
    application/json
```

--------------------------------

### Retrieve Ownership or Control Statement API

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/ownership-or-control-statement

This API endpoint allows users to retrieve detailed ownership and control information for a specific individual. The request is an HTTP GET, and the response is a JSON array of ownership objects, each containing comprehensive details such as statement ID, type, timestamps, full name, interests, publication details, and associated links.

```APIDOC
Endpoint: GET /api-documentation/bo-api-reference/ownership-or-control-statement/{individualId}
Description: Retrieves ownership and control information for a specific individual.

Response (JSON Array of Objects):
[
  {
    "statementId": "string",
    "type": "string",
    "creationTimestamp": "string (ISO 8601 datetime)",
    "modificationTimestamp": "string (ISO 8601 datetime)",
    "fullName": "string",
    "interests": "array of objects",
    "publicationDetails": "object",
    "links": "array of objects"
  }
]

Details of Ownership Object Fields:
- statementId: Unique identifier for the statement.
- type: Type of the ownership statement.
- creationTimestamp: Date and time of statement creation.
- modificationTimestamp: Date and time of last modification.
- fullName: Full name of the individual.
- interests: Details about the individual's interests (e.g., type, value).
- publicationDetails: Information about where and when the statement was published.
- links: Related links (e.g., rel, href).
```

--------------------------------

### Retrieve Natural Person Statement Details API

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/natural-person-statement

This API endpoint allows an HTTP GET request to retrieve the details of a natural person using a specified statement ID. The response provides an array of 'persons details' including statement ID, verification status, dates, nationalities, names, demographics, gender, date of birth, country of residence, and addresses, along with an array of 'links' for related hypermedia.

```APIDOC
GET /natural-person-statement/{statementId}

Description: This API endpoint makes an HTTP GET request to retrieve the details of a natural person with the specified statement ID.

Parameters:
  statementId:
    Type: string (Path Parameter)
    Description: The unique identifier for the natural person statement.

Response (200 OK):
  Body:
    Type: array of objects (persons details)
    Properties:
      statement ID: string
      verification status: string
      creation date: string (ISO 8601)
      modification date: string (ISO 8601)
      nationalities: array of strings
      names: array of objects (e.g., { "first_name": "string", "last_name": "string" })
      demographic details: object
      gender: string
      date of birth: string (YYYY-MM-DD)
      country of residence: string
      addresses: array of objects
      links: array of objects (hypermedia links, e.g., { "rel": "string", "href": "string" })
```

--------------------------------

### Retrieve Beneficial Ownership Supporting Documents API

Source: https://guide.cipc.co.za/api-documentation/bo-api-reference/supporting-documents

This API endpoint allows users to retrieve documentation associated with a specific beneficial ownership registration using its statement ID. The response provides an array of document details including ID, registration ID, reference number, content type, creation date, document type, status, and name, along with related links. Further details are required for adding documentation.

```APIDOC
API Endpoint:
  GET /api/bo-api-reference/supporting-documents/{statementId}

Purpose:
  Retrieve documentation for a specific beneficial ownership registration by statement ID.

Response Body:
  Type: JSON Array
  Description: An array of documents with their details and an array of links.

  Document Object Properties:
    - documentation ID: string
    - registration ID: string
    - reference number: string
    - content type: string
    - created date: string (date-time format)
    - document type description: string
    - document status description: string
    - document name: string

  Link Object Properties:
    - relation: string
    - href: string (URL)

Notes:
  - To "Add documentation", further details about specific requirements are needed.
```

--------------------------------

### Beneficial Ownership (BO) API Reference Endpoints

Source: https://guide.cipc.co.za/api-documentation

This section details the endpoints available under the Beneficial Ownership (BO) API, which focuses on statements related to entity ownership, control, natural persons, and supporting documents.

```APIDOC
BO API reference:
  - Entity statement
  - Ownership or control statement
  - Natural person statement
  - Supporting documents
  - Individual document
```

--------------------------------

### Companies API Reference Endpoints

Source: https://guide.cipc.co.za/api-documentation

This section outlines the available endpoints within the Companies API, providing access to various company-related information such as profiles, appointments, directors, and filing history.

```APIDOC
Companies API reference:
  - Companyprofile
  - Information
  - Appointments
  - Directors
  - Employee verification
  - Registered office address
  - Filing history
```

--------------------------------

### API Endpoint Definition for Company Director Appointments

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/appointments

This section outlines the POST endpoint for accessing company director appointment details. It specifies the URL, required body parameters (enterprise_number, identity_number), and potential HTTP responses (200 for success, 401 for unauthorized access).

```APIDOC
### Company director appointment
post
https://cipc-apm-rs-dev.azure-api.net/enterprise/v1/appointments
Get details of an individual company director appointment

Authorizations
apiKeyHeader
apiKeyHeaderapiKeyQuery

Body
enterprise_numberstringRequired
identity_numberstringRequired

Responses
200
Read Director Profile
application/json
Responseobject
Show properties
401
Unauthorised
application/json
```

--------------------------------

### CIPC API Access Token Response

Source: https://guide.cipc.co.za/getting-started/authorization

This snippet illustrates the expected successful HTTP 200 OK response from the `/oauth2/token` endpoint, containing the access_token, token_type, expires_in, and refresh_token.

```HTTP
HTTP/1.1 200 OK
Request URL: <example.com>/oauth2/token
Date: <EEE, dd MMM yyyy HH:mm:ss z>
Content-Length: 500
Body: {
  "access_token": "eyJ...124nOvc",
  "token_type": "bearer",
  "expires_in" : 3600,
  "refresh_token": "eyJ...124nOvc"
}
```

--------------------------------

### API Reference: POST /filing-history Endpoint

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/filing-history

Detailed API documentation for the POST /enterprise/v1/filing-history endpoint, used to retrieve a company's annual returns filing history. It requires an 'enterprise_number' in the request body and supports API key authorization. Returns filing history on success (200) or an unauthorized error (401).

```APIDOC
Method: POST
Path: /enterprise/v1/filing-history
Description: Return annual returns filing history
Authorizations:
  - apiKeyHeader
  - apiKeyQuery
Request Body:
  enterprise_number:
    Type: string
    Required: true
    Description: The company number of the company information to return.
Responses:
  200:
    Description: annual returns filing history
    Content-Type: application/json
    Schema: Responseobject (Show properties)
  401:
    Description: Unauthorised
    Content-Type: application/json
```

--------------------------------

### API Documentation: Retrieve Company Directors

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/directors

Comprehensive API documentation for the POST /enterprise/v1/directors endpoint, used to retrieve a list of company directors. Details request body parameters, authorization requirements, and expected success (200) and error (401) responses, including the structure of the director list.

```APIDOC
Endpoint: POST https://cipc-apm-rs-dev.azure-api.net/enterprise/v1/directors
Description: List of all company directors

Authorizations:
  - apiKeyHeader
  - apiKeyQuery

Request Body:
  Content-Type: application/json
  Schema:
    enterprise_number (string, Required): The company number of the company information to return.

Responses:
  200 OK (application/json):
    Description: directorList
    Schema:
      {
        "directors_list": [
          {
            "first_names": "string",
            "surname": "string",
            "initials": "string",
            "identity_number": "string",
            "date_of_birth": "string",
            "director_status": "string",
            "enterprise_number": "string",
            "enterprise_name": "string",
            "director_type": "string",
            "designation": "string",
            "enterprise_type": "string",
            "enterprise_status": "string",
            "registration_date": "string",
            "appointment_date": "string",
            "resignation_date": "string",
            "country_code": "string",
            "member_size_interest": 0,
            "member_contribution": 0,
            "residential_address_1": "string",
            "residential_address_2": "string",
            "residential_address_3": "string",
            "residential_address_4": "string",
            "residential_postal_code": "string"
          }
        ]
      }
  401 Unauthorized (application/json):
    Description: Unauthorised
```

--------------------------------

### API Endpoint Definition: Registered Office Address

Source: https://guide.cipc.co.za/api-documentation/companies-api-reference/registered-office-address

Defines the POST endpoint for retrieving a company's registered office address, detailing the URL, required authorizations, request body parameters, and possible HTTP responses with their content types.

```APIDOC
post /enterprise/v1/registered-office-address
  Description: Return company registered office address
  Authorizations:
    - apiKeyHeader
    - apiKeyHeaderapiKeyQuery
  Request Body:
    Description: The company number of the company information to return.
    Parameters:
      - name: enterprise_number
        type: string
        required: true
  Responses:
    200:
      Description: registered office address
      Content-Type: application/json
      Schema: Response object
    401:
      Description: Unauthorised
      Content-Type: application/json
```
Tokens:
Raw