> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/organizations/lookup-organizations) 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.

<Callout icon="bell" color="#FFCA16" iconType="regular">
  ###### 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.
</Callout>

<Callout icon="bell" color="#FFCA16" iconType="regular">
  ###### 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.
</Callout>

### Example: Creating an Organization

This example shows a standard request to create an organization with organizationToken retrieved from the [/lookup](/api-reference/organizations/lookup-organizations) 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

<CodeGroup>
  ```bash Request - Create Organization theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDktMTBUMDQ6Mzc6MDIuMDg3MDU3MzMzWiIsIm9uIjpbeyJybiI6IjYxNjIzNTA2ODkyIiwicmEiOiJBQk4ifSx7InJuIjoiNjIzNTA2ODkyIiwicmEiOiJBQ04ifV0sInByb3YiOiJjcmVkaXRvcndhdGNoIiwiY28iOiJBVVMifQ=="
  }'
  ```
</CodeGroup>

#### Response

<CodeGroup>
  ```json Response - Create Organization theme={null}
  {
      "organization": {
          "createdAt": "2025-09-10T04:53:46Z",
          "details": {
              "registrationDetails": [
                  {
                      "registrationNumber": "61623506892",
                      "registrationNumberType": "ABN",
                      "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
                  },
                  {
                      "registrationNumber": "623506892",
                      "registrationNumberType": "ACN",
                      "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
                  }
              ]
          },
          "entityId": "019931f9-02a2-7c87-816c-c9e6743eaae5",
          "entityType": "ORGANIZATION",
          "informationSources": {
              "ec13d19f-c725-4397-a575-92c65c070f23": {
                  "createdAt": "2025-09-10T04:53:46.674358Z",
                  "isAuthoritative": true,
                  "provider": "CREDITOR_WATCH",
                  "requestedAt": "2025-09-10T04:37:02Z",
                  "source": "ASIC",
                  "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
              }
          },
          "schemaVersion": 2,
          "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23",
          "updatedAt": "2025-09-10T04:53:46Z"
      },
      "requestId": "01K4RZJ0CGM3PWCRS5NRH4WXMA",
      "serviceProfiles": [
          {
              "createdAt": "2025-09-10T04:53:46.9539Z",
              "createdRequestId": "01K4RZJ0CGM3PWCRS5NRH4WXMA",
              "entityId": "019931f9-02a2-7c87-816c-c9e6743eaae5",
              "entityName": "FRANKIE FINANCIAL PTY LTD",
              "entityType": "ORGANIZATION",
              "serviceName": "DEFAULT",
              "serviceProfileId": "86cf3db8-a9f5-433d-b446-35927096d327",
              "state": "INIT",
              "subscriptions": [],
              "updatedAt": "2025-09-10T04:53:46.9539Z"
          }
      ]
  }
  ```
</CodeGroup>

### 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-reference/organizations/get-an-organization-entity) API documentation.
To understand ownership structure of the organization, please refer to [understanding organization ownership](/docs/kyb/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

<CodeGroup>
  ```bash Request - Retrieve Organization theme={null}
      curl --location 'https://api.uat.frankie.one/v2/organizations/019931f9-02a2-7c87-816c-c9e6743eaae5' \
      --header 'api_key: YOUR_API_KEY' \
      --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>

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`.

<Danger>
  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.
</Danger>

### Deleting an Organization

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

#### Request

<CodeGroup>
  ```bash Request - Delete Organization theme={null}
      curl --location --request DELETE 'https://api.uat.frankie.one/v2/organizations/019931f9-02a2-7c87-816c-c9e6743eaae5' \
      --header 'api_key: YOUR_API_KEY' \
      --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>