KYBImplementation Guide

Creating & Managing Organizations

A guide to the complete lifecycle of an 'organization' entity, from creation and retrieval to deletion.

The organization is a core object in the FrankieOne platform, representing a business. This guide covers the complete lifecycle of creating and managing these entities via the API.

1. Creating an Organization

To create an organization entity, send a POST request with the organizationToken retrieved from the /lookup endpoint. A successful request will return a 201 Created status and the organization object, including a unique entityId. The entityId returned in the response can be used for subsequent operations, such as executing a workflow.

Warning: organizationToken Expiry

The organizationToken retrieved from the lookup endpoint does not last forever. If your request fails indicating invalid organizationToken, you will need to perform a new lookup to retrieve a new organizationToken.

Warning: A new entity is created for each request

A new entity is created for each request. We do not de-duplicate entities based on organizationToken in this request.

Example: Creating an Organization

This example shows a standard request to create an organization with organizationToken retrieved from the /lookup endpoint.

  1. In the example below, replace YOUR_CUSTOMER_ID with your Customer ID and YOUR_API_KEY with your API key provided by FrankieOne.
  2. Copy the resulting code into your command line, and run the command.

Request

Request - Create Organization
1curl --location 'https://api.uat.frankie.one/v2.1/organizations' \
2--header 'api_key: YOUR_API_KEY' \
3--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
4--header 'Content-Type: application/json' \
5--data '{
6    "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDktMTBUMDQ6Mzc6MDIuMDg3MDU3MzMzWiIsIm9uIjpbeyJybiI6IjYxNjIzNTA2ODkyIiwicmEiOiJBQk4ifSx7InJuIjoiNjIzNTA2ODkyIiwicmEiOiJBQ04ifV0sInByb3YiOiJjcmVkaXRvcndhdGNoIiwiY28iOiJBVVMifQ=="
7}'

Response

Response - Create Organization
1{
2    "organization": {
3        "createdAt": "2025-09-10T04:53:46Z",
4        "details": {
5            "registrationDetails": [
6                {
7                    "registrationNumber": "61623506892",
8                    "registrationNumberType": "ABN",
9                    "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
10                },
11                {
12                    "registrationNumber": "623506892",
13                    "registrationNumberType": "ACN",
14                    "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
15                }
16            ]
17        },
18        "entityId": "019931f9-02a2-7c87-816c-c9e6743eaae5",
19        "entityType": "ORGANIZATION",
20        "informationSources": {
21            "ec13d19f-c725-4397-a575-92c65c070f23": {
22                "createdAt": "2025-09-10T04:53:46.674358Z",
23                "isAuthoritative": true,
24                "provider": "CREDITOR_WATCH",
25                "requestedAt": "2025-09-10T04:37:02Z",
26                "source": "ASIC",
27                "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
28            }
29        },
30        "schemaVersion": 2,
31        "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23",
32        "updatedAt": "2025-09-10T04:53:46Z"
33    },
34    "requestId": "01K4RZJ0CGM3PWCRS5NRH4WXMA",
35    "serviceProfiles": [
36        {
37            "createdAt": "2025-09-10T04:53:46.9539Z",
38            "createdRequestId": "01K4RZJ0CGM3PWCRS5NRH4WXMA",
39            "entityId": "019931f9-02a2-7c87-816c-c9e6743eaae5",
40            "entityName": "FRANKIE FINANCIAL PTY LTD",
41            "entityType": "ORGANIZATION",
42            "serviceName": "KYB",
43            "serviceProfileId": "86cf3db8-a9f5-433d-b446-35927096d327",
44            "state": "INIT",
45            "subscriptions": [],
46            "updatedAt": "2025-09-10T04:53:46.9539Z"
47        }
48    ]
49}

The organization Object

The organization object holds all the information about the business. Organization details holds the organization details including registration details, organization name etc. For more details on the fields in the organization object, please refer to our retrieve organization API documentation. To understand ownership structure of the organization, please refer to understanding organization ownership documentation.

Information Sources

organization object also includes informationSources which is a map of information source Ids to information source objects. These objects indicate the vendor and registry from which information was retrieved, and when it was requested. Data points in the organization object are then tagged with this sourceId.

Service Profiles

If a serviceName is passed in the Create Organization request, a service profile of that service gets created as part of the entity creation. If no serviceName is passed, a default service profile is created. serviceProfiles is an array of service profile objects associated with the organization.

2. Retrieving an Organization

To fetch the current state of an organization entity, use a GET request with their unique entityId.

Request

Request - Retrieve Organization
1curl --location 'https://api.uat.frankie.one/v2.1/organizations/019931f9-02a2-7c87-816c-c9e6743eaae5' \
2--header 'api_key: YOUR_API_KEY' \
3--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'

The response will contain the full organization object, similar to the response from the creation request. If you’ve retrieved additional data points for the entity, by running the profile/ownership workflows, they will also be included in the response.

3. Deleting an Organization

You can delete an organization entity using the DELETE endpoint with their entityId.

Deletion is Permanent

Deleting an entity is an irreversible action. This data cannot be recovered. Only perform deletions when you are certain the data is no longer required for any operational, audit, or compliance purpose.

Deleting an Organization

To permanently remove an organization and all their associated data, use the DELETE endpoint with their entityId.

Request

Request - Delete Organization
1curl --location --request DELETE 'https://api.uat.frankie.one/v2.1/organizations/019931f9-02a2-7c87-816c-c9e6743eaae5' \
2--header 'api_key: YOUR_API_KEY' \
3--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'