Manage companies with our API

Learn about creating and managing companies, their connections, and their data via API

Onboard your users

Your users or customers are companies. To access their data you'll need to onboard them.

To onboard a new user or customer:

1. Create a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.
2. Authorize access to sources of data
3. Read the data

You can either onboard users:

• When they first create an account with your service
• At the first point you want to retrieve their financial data

Create a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.

To create a new companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources., use the Create company endpoint and provide a name for the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. in the request body. The name parameter is mandatory to execute this request. You can also provide a description to store additional information about the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources..

TypeScript

platformClient.companies.create({
    name: "Toft stores",
    description: "Need a loan for refurb."
}).then((companyCreatedRes: CreateCompanyResponse) => {
    if (companyCreatedRes.statusCode == 200) {
        console.log(companyCreatedRes.company.id, companyCreatedRes.company.name)
    }
});

Python

req = shared.CompanyRequestBody(
    name='Toft stores',
    description='Need a loan for refurb.'
    )

company_created_res = platform_client.companies.create(req)
print(company_created_res.company.id, company_created_res.company.name)

C#

var companyCreatedRes = await platformClient.Companies.CreateAsync(new CompanyRequestBody() {
    Name = "Toft stores",
    Description = "Need a loan for refurb."
  });

if(companyCreatedRes.Company != null) {
    var company = companyCreatedRes.Company;
    logger.LogInformation('{CompanyId} {CompanyName}', company.Id, company.Name);
}

Go

ctx := context.Background()

companyCreatedRes, err := platformClient.Companies.Create(ctx, shared.CompanyRequestBody{
    Name: "Toft stores",
    Description: "Need a loan for refurb."
})

if err != nil {
    log.Fatal(err)
}

if companyCreatedRes.Company != nil {
    fmt.Println("%s %s", companyCreatedRes.Company.Id, companyCreatedRes.Company.Name)
}

Java

CompanyRequestBody req = CompanyRequestBody.builder()
    .name("Toft stores")
    .description("Need a loan for refurb.")
    .build();

CreateCompanyResponse companyCreatedRes = platformClient.companies().create()
    .request(req)
    .call();

if (companyCreatedRes.company().isPresent()) {
    // handle response
}

Retain the company ID

The id property that you receive in the response is the unique Codat identifier for this companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.. We recommend that you retain it for future reference.

Company name

The name of the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. helps you identify the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. in the Codat Portal and doesn't have to be unique. Make sure to avoid forbidden characters.

Add metadata to a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.

You can enrich a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. profile with additional information using the tags object. These tags provide flexible ways to store metadata.

For example, you can set foreign key associations, define operational regions, or record specific details about the financial services a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. has requested.

Each companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. can have up to 10 tags that you can add using the Create company endpoint or when updating the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. via the Update company endpoint.

Use tags with webhooks

You can use the tags object to filter companies to specific webhookWebhook An automated notification sent from Codat to your application when specific events occur, such as when data syncs complete or connections change status. consumers. To learn more, see Filter webhooks by company tags.

For example, here's how you can add tags that define a user-defined ID (UID) and operating region:

Create company

TypeScript

platformClient.companies.create({
    name: "Toft stores",
    tags: {
      uid: "cust_1MtJUT2eZvKYlo2CNaw2HvEv",
      region: "uk"
    }
}).then((companyCreatedRes: CreateCompanyResponse) => {
    if (companyCreatedRes.statusCode == 200) {
        console.log(companyCreatedRes.company.id, companyCreatedRes.company.name)
    }
});

Python

req = shared.CompanyRequestBody(
  name='Toft stores',
  tags={
    'uid': 'cust_1MtJUT2eZvKYlo2CNaw2HvEv',
    'region': 'uk'
  }
)

company_created_res = platform_client.companies.create(req)
print(company_created_res.company.id, company_created_res.company.name)

C#

var companyCreatedRes = await platformClient.Companies.CreateAsync(new CompanyRequestBody() {
    Name = "Toft stores",
    Tags = new Dictionary<string, string>(){
      ["uid"] = "cust_1MtJUT2eZvKYlo2CNaw2HvEv",
      ["region"] = "uk"
    }
});

if(companyCreatedRes.Company != null) {
    var company = companyCreatedRes.Company;
    logger.LogInformation('{CompanyId} {CompanyName}', company.Id, company.Name);
}

Go

ctx := context.Background()

companyCreatedRes, err := platformClient.Companies.Create(ctx, shared.CompanyRequestBody{
    Name: "Toft stores",
    Tags: map[string]string{
      "uid": "cust_1MtJUT2eZvKYlo2CNaw2HvEv",
      "region": "uk"
    }
})

if err != nil {
    log.Fatal(err)
}

if companyCreatedRes.Company != nil {
    fmt.Println("%s %s", companyCreatedRes.Company.Id, companyCreatedRes.Company.Name)
}

Java

CompanyRequestBody req = CompanyRequestBody.builder()
    .name("Toft stores")
    .tags(
      java.util.Map.ofEntries(
        entry("uid", "cust_1MtJUT2eZvKYlo2CNaw2HvEv"),
        entry("region", "uk")
      )
    )
    .build();

CreateCompanyResponse companyCreatedRes = platformClient.companies().create()
    .request(req)
    .call();

if (companyCreatedRes.company().isPresent()) {
    // handle response
}

Update company

TypeScript

platformClient.companies.update({
  companyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
  companyRequestBody: {
    name: "Toft stores",
    tags: {
      uid: "cust_1MtJUT2eZvKYlo2CNaw2HvEv",
      region: "uk"
    }
  }
}).then((companyUpdatedRes: UpdateCompanyResponse) => {
    if (companyUpdatedRes.statusCode == 200) {
        console.log(companyUpdatedRes.company.id, companyUpdatedRes.company.name)
    }
});

Python

req = shared.CompanyRequestBody(
  name='Toft stores',
  tags={
    'uid': 'cust_1MtJUT2eZvKYlo2CNaw2HvEv',
    'region': 'uk'
  }
)

company_updated_res = platform_client.companies.update(
    request=operations.UpdateCompanyRequest(
        company_id='8a210b68-6988-11ed-a1eb-0242ac120002',
        company_request_body=req
    )
)
print(company_updated_res.company.id, company_updated_res.company.name)

C#

var companyCreatedRes = await platformClient.Companies.UpdateAsync(new UpdateCompanyRequest() {
  CompanyId: "8a210b68-6988-11ed-a1eb-0242ac120002",
  CompanyRequestBody = new CompanyRequestBody() {
    Name = "Toft stores",
    Tags = new Dictionary<string, string>(){
      ["uid"] = "cust_1MtJUT2eZvKYlo2CNaw2HvEv",
      ["region"] = "uk"
    }
  }
});

if(companyCreatedRes.Company != null) {
    var company = companyCreatedRes.Company;
    logger.LogInformation('{CompanyId} {CompanyName}', company.Id, company.Name);
}

Go

ctx := context.Background()

companyUpdatedRes, err := platformClient.Companies.Create(ctx, operations.UpdateCompanyRequest{
  CompanyID: "8a210b68-6988-11ed-a1eb-0242ac120002",
  CompanyRequestBody: shared.CompanyRequestBody{
    Name: "Toft stores",
    Tags: map[string]string{
      "uid": "cust_1MtJUT2eZvKYlo2CNaw2HvEv",
      "region": "uk"
    }
  }
})

if err != nil {
    log.Fatal(err)
}

if companyUpdatedRes.Company != nil {
    fmt.Println("%s %s", companyUpdatedRes.Company.Id, companyUpdatedRes.Company.Name)
}

Java

UpdateCompanyRequest req = UpdateCompanyRequest.builder()
    .companyId("8a210b68-6988-11ed-a1eb-0242ac120002")
    .companyRequestBody(CompanyRequestBody.builder()
        .name("Bank of Dave")
        .tags(
            java.util.Map.ofEntries(
              entry("uid", "cust_1MtJUT2eZvKYlo2CNaw2HvEv"),
              entry("region", "uk")
            )
        ).build()
    )
    .build();

UpdateCompanyResponse companyUpdatedRes = platformClient.companies().update()
    .request(req)
    .call();

if (companyUpdatedRes.company().isPresent()) {
    // handle response
}

Updating a company with existing tags

If you use include a null or empty tags object in the Update company endpoint request, any existing tags for this companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. will be removed. To retain existing tags, ensure they are included in the update.

Filter companies by metadata

Once you have enriched the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. with additional metadata in the form of tags, you can use it for filtering. This allows you to retrieve companies based on specific criteria, such as finding a specific companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. by customer ID or retrieving a group of companies that the same tag.

To do so, use the tags query parameter on the List companies endpoint. The tags query parameter uses the same query language as Codat's query parameters. See more on querying in Query data.

Here is a query example that returns a specific companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. by a customer ID:

TypeScript

const result = await platformClient.companies.list({
  tags: `uid=${customerId}`,
});

Python

res = platform_client.companies.list(
    request=operations.ListCompaniesRequest(
        tags=f'uid={customerId}'
    )
)

C#

var res = await platformClient.Companies.ListAsync(new() {
    Tags = $"uid={customerId}",
});

Go

ctx := context.Background()
res, err := platformClient.Companies.List(ctx, operations.ListCompaniesRequest{
    Tags: platform.String(fmt.Sprintf("uid=%d", customerId)),
})

Java

ListCompaniesRequest req = ListCompaniesRequest.builder()
  .tags(String.format("uid=%d", customerId))
  .build();

ListCompaniesResponse res = platformClient.companies().list()
  .request(req)
  .call();

Authorize access to companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. data

Once you've created the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources., they'll need to give you permission to read their data from a given source, like their accounting software. There are several approaches to doing this, but for simplicity we've just covered our out-of-the-box hosted link approach.

Send the user to the redirect URL returned in the previous step. They will be sent to Link where they can select their accounting software and complete the linking process.

Once the user has completed the LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. flow, the Codat platform will redirect them to the redirect URL you have configured in the Settings > Auth flow > LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. in the Codat Portal. This URL can include the Codat companyId as well as any other custom query parameters.

Redirect parameter settings

For more information on setting your redirect URL, refer to this document.

Once your user is redirected to the redirect URL page, they'll be able to authorize access to their data. Once this is successful, the linking process is complete and their data can be read.

Re-authorize access

Occasionally the Data ConnectionsConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform. of a Codat companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. will go into a deauthorized state. This indicates that Codat’s linkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. to the platform is no longer valid, and you will not be able to queue any further data syncsSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. for that connectionConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform.. You will still be able to query data previously retrieved from the platform.

Data ConnectionsConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform. can become deauthorized by the user revoking access to their accounting software or due to platform limitations such as Xero's limited access period for non-partner companies.

To enable you to refresh the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources.'s data, you will need to ask the user to complete the auth flow in LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. again.

Re-linking and usage costs

Creating a new companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. may cause additional data to be read from the platform and is likely to incur additional usage costs.

Redirect the user to complete the auth flow

Get a redirect URL for the companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. by following the process here. Send the user to the redirect URL. They will be prompted to select their accounting software and complete the linking process using the Link flow.

Once the user finishes the LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. flow, they will be redirected back to the Redirect URL, as described earlier in this guide. At this point the re-authorization process is complete and their data has begun synchronizing again.

Delete companies

You can delete a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. and its data using the Delete company endpoint.

TypeScript

const companyDeleteResponse = await platformClient.companies.delete({
  companyId: companyCreatedRes.company.id,
});

Python

company_delete_response = platform_client.companies.delete(
  operations.DeleteCompanyRequest(
    company_id=company_created_res.company.id,
  )
)

C#

var companyDeleteResponse = await platformClient.Companies.DeleteAsync(new(){
    CompanyId = companyCreatedRes.Company.Id,
});

Go

ctx := context.Background()
companyDeleteResponse, err := platformClient.Companies.Delete(ctx, operations.DeleteCompanyRequest{
    CompanyID: companyCreatedRes.Company.ID,
})

Recap

You've learned:

• How to create a companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. and authorize access to their data
• The basics of reading data
• Manage companies

---

Read next

• Get data
• Create, update and delete data
• Filter webhooks by company tags