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 company
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 company

To create a new company, use the Create company endpoint and provide a name for the company 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 company.

TypeScript

platformClient.companies.create({
    name: "Platypus Properties",
    description: "Platypuses are venomous mammals"
}).then((companyCreatedRes: CreateCompanyResponse) => {
    if (companyCreatedRes.statusCode == 200) {
        console.log(companyCreatedRes.company.id, companyCreatedRes.company.name)
    }
});

Python

req = shared.CompanyRequestBody(
    name='Platypus Properties',
    description='Platypuses are venomous mammals'
    )

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 = "Platypus Properties",
    Description = "Platypuses are venomous mammals"
  });

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: "Platypus Properties",
    Description: "Platypuses are venomous mammals"
})

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

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

Retain the company ID

The id property that you receive in the response is the unique Codat identifier for this company. We recommend that you retain it for future reference.

Company name

The name of the company doesn't have to be unique. It's just there to help you identify the company in the portal. Make sure to avoid forbidden characters.

Authorize access to company data

Once you've created the company, 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 Link flow, the Codat platform will redirect them to the redirect URL you have configured in the Settings > Auth flow > Link 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 Connections of a Codat company will go into a deauthorized state. This indicates that Codat’s link to the platform is no longer valid, and you will not be able to queue any further data syncs for that connection. You will still be able to query data previously retrieved from the platform.

Data Connections 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 company's data, you will need to ask the user to complete the auth flow in Link again.

Re-linking and usage costs

Creating a new company 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 company 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 Link 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 company 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,
})

Manage groups of companies

You can use our groups feature and assign a company to one or more groups. You might choose to group companies based on the different products and services you provide, your internal team structures, different geographies, and more.

If you're grouping companies for the first time, you need to create a group first using the Create group endpoint. You only need to do this operation once per group, so retain the groupId to reuse it within your application.

You can see any groups you've already created using the List groups endpoint.

TypeScript

const groupCreateResponse = await platformClient.groups.create({
  name: "Invoice finance team",
});

if (groupCreateResponse.statusCode == 200) {
  //Assign to global param:
  groupId = groupCreateResponse.group.id
  console.log(groupId)
}

Python

group_create_response = platform_client.groups.create(
  shared.GroupPrototype(
    name='Invoice finance team',
))

if group_create_response.group is not None:
  # Assign to global param:
  group_id = group_create_response.group.id
  print(group_id)

C#

var groupCreateResponse = await platformClient.Groups.CreateAsync(new(){
  Name = "Invoice finance team",
});

if(groupCreateResponse.Group != null){
  //Assign to global param:
  groupId = groupCreateResponse.group.Id;
  Console.WriteLine(groupId);
}

Go

ctx := context.Background()
groupCreateResponse, err := s.Groups.Create(ctx, &shared.GroupPrototype{
    Name: platform.String("Invoice finance team"),
})
if err != nil {
  //Assign to global param:
  groupID = groupCreateResponse.Group.ID
  fmt.Println(groupID)
}

Create new groups with care

It's not possible to update or delete existing groups, so double-check that the group's name is correct when creating it.

Once you have created a group, you can assign a company to it in two ways: either at the point of company creation or after it has been created. For a new company, use the Create company endpoint and pass the groupId that you want to add the company to.

TypeScript

platformClient.companies.create({
    name: "Platypus Properties",
    groups: [{ id: groupId }]
}).then((companyCreatedRes: CreateCompanyResponse) => {
    if (companyCreatedRes.statusCode == 200) {
      const company = companyCreatedRes.company
      console.log(company.id, company.name, company.groups[0].id)
    }
});

Python

company_created_req = shared.CompanyRequestBody(
  name='Platypus Properties',
  groups=[shared.GroupRef(id=group_id)]
)

company_created_res = platform_client.companies.create(company_created_req)
company = company_created_res.company
print(company.id, company.name, company.groups[0].id)

C#

var companyCreatedRes = await platformClient.Companies.CreateAsync(new() {
    Name = "Platypus Properties",
    Groups = new List<GroupRef>(){
      new(){ Id = groupId }
    }
  });

if(companyCreatedRes.Company != null) {
    var company = companyCreatedRes.Company;
    logger.LogInformation("{CompanyId} {CompanyName} {GroupId}", company.Id, company.Name, company.Groups[0].Id);
}

Go

ctx := context.Background()
companyCreatedRes, err := platformClient.Companies.Create(ctx, shared.CompanyRequestBody{
    Name: "Platypus Properties",
    Groups: []shared.GroupRef{
      shared.GroupRef{ ID: groupID }
    }
})

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

if companyCreatedRes.Company != nil {
  company := companyCreatedRes.Company
  fmt.Println("%s %s %s", company.ID, company.Name, company.Groups[0].ID)
}

If you need to add an existing company to a group, use the Add company to group endpoint.

TypeScript

const companyAddRes = await sdk.groups.addCompany({
  companyGroupAssignment: {
    groupId: groupId,
  },
  companyId: company.id,
});

Python

company_add_req = operations.AddCompanyToGroupRequest(
  company_group_assignment=shared.CompanyGroupAssignment(
    group_id=group_id,
  ),
  company_id=company.id,
)

company_add_res = platform_client.groups.add_company(company_add_req)

C#

var companyAddRes = await platformClient.Groups.AddCompanyAsync(new() {
  CompanyGroupAssignment = new CompanyGroupAssignment() {
    GroupId = groupId,
  },
  CompanyId = company.Id,
});

Go

ctx := context.Background()
companyAddRes, err := platformClient.Groups.AddCompany(ctx, operations.AddCompanyToGroupRequest{
  CompanyGroupAssignment: &shared.CompanyGroupAssignment{
    GroupID: platform.String(groupID),
  },
  CompanyID: company.ID,
})

To remove a company from a group, use the Remove company from group endpoint.

TypeScript

const companyRemoveRes = await platformClient.groups.removeCompany({
  companyId: company.id,
  groupId: groupId,
});

Python

company_remove_req = operations.RemoveCompanyFromGroupRequest(
  company_id=company.id,
  group_id=group_id,
)

company_remove_res = platform_client.groups.remove_company(company_remove_req)

C#

var companyRemoveRes = await platformClient.Groups.RemoveCompanyAsync(new() {
  CompanyId = company.Id,
  GroupId = groupId,
});

Go

ctx := context.Background()
companyRemoveRes, err := s.Groups.RemoveCompany(ctx, operations.RemoveCompanyFromGroupRequest{
  CompanyID: company.ID,
  GroupID: groupID,
})

Recap

You've learned:

• How to create a company and authorize access to their data
• The basics of reading data
• Manage companies
• Manage groups

---

Read next

• Get data
• Create, update and delete data