Skip to content

Create projects with the API

If you manage Enfonica for your own customers, you can give each customer their own project and create it from your app. A project holds a customer's phone numbers, SIP domains, and everything else that they use on Enfonica. Its usage is charged to a billing account.

Creating a project that's ready to use takes two calls: create the project, and then link it to a billing account. Until it's linked, the project exists but can't use anything that's charged for.

Before you begin

  • Create an organisation's service account with the Editor or Owner role, and download its key file. It works in every project in your organisation, including the projects that your app creates.
  • Use the key file to get an access token, as described in Authentication, and send it in each request as Authorization: Bearer $TOKEN.

Projects are at https://resourcemanager.api.enfonica.com, and billing is at https://billing.api.enfonica.com. Responses use camelCase field names. Requests accept camelCase or snake_case.

Find your billing account

List the billing accounts that you can use:

curl "https://billing.api.enfonica.com/v1beta1/billingAccounts" \
  -H "Authorization: Bearer $TOKEN"

{
  "billingAccounts": [
    {
      "name": "billingAccounts/AB12-CD34-EF56",
      "displayName": "ACME Communications",
      "currencyCode": "AUD",
      "open": true
    }
  ]
}

Keep the name of the account that your customers' usage is charged to. It rarely changes, so you can store it in your app's configuration.

List your projects

curl "https://resourcemanager.api.enfonica.com/v1/projects?pageSize=100" \
  -H "Authorization: Bearer $TOKEN"

{
  "projects": [
    {
      "name": "projects/acme-10042",
      "displayName": "Northwind Dental",
      "createTime": "2026-10-27T03:12:44Z",
      "lifecycleState": "ACTIVE"
    }
  ],
  "nextPageToken": "…"
}

An organisation's service account sees every project in your organisation. Each page has up to 100 projects. To get the next page, add pageToken with the nextPageToken from the previous response. Deleted projects are left out unless you add showDeleted=true.

To get one project, use GET /v1/projects/acme-10042.

Create a project

Create the project

curl -X POST "https://resourcemanager.api.enfonica.com/v1/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "projects/acme-10042", "displayName": "Northwind Dental" }'

You choose the project ID, acme-10042 in this example:

  • It must be unique across all of Enfonica, not just your organisation, and you can't change it later. Build it from something that's unique to you, such as a short prefix for your business followed by your customer number.
  • It must be 2 to 30 characters long, and contain only lowercase letters, digits, and hyphens. It must start and end with a letter or a digit.
  • If the ID is already taken, the request fails with an ALREADY_EXISTS error. To find out whether the project is one of yours, for example because you're retrying after a timeout, get it with GET /v1/projects/acme-10042. If it's in your organisation, the request returns it, so carry on and link it to your billing account. If the request fails, the ID belongs to someone else, so choose another ID.

The displayName can be up to 100 characters long. You can change it later with PATCH /v1/projects/acme-10042?updateMask=displayName.

The service account becomes the owner of each project that it creates.

curl -X PUT "https://billing.api.enfonica.com/v1beta1/projects/acme-10042/billingInfo" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "billingAccount": "billingAccounts/AB12-CD34-EF56" }'

{
  "parent": "projects/acme-10042",
  "billingAccount": "billingAccounts/AB12-CD34-EF56",
  "billingEnabled": true
}

When billingEnabled is true, the project is ready to use.

Linking the same billing account again changes nothing, so this call is always safe to repeat. If it times out or fails with UNAVAILABLE (HTTP 503) or another 5xx error, retry it with backoff, up to a limit. Don't retry any other error, such as PERMISSION_DENIED, NOT_FOUND for a wrong billing account, or FAILED_PRECONDITION, because repeating the same request won't fix it. Report it instead, and report it when you reach the retry limit. To check a project's link at any time, use GET https://billing.api.enfonica.com/v1beta1/projects/acme-10042/billingInfo. If billingEnabled is false, the project has no open billing account and can't use services that are charged for.

Put it together

For each new customer, your app does the following:

  1. Creates the project with POST /v1/projects. If it gets ALREADY_EXISTS for an ID that it created earlier, it treats that as success.
  2. Links the project with PUT /v1beta1/projects/{id}/billingInfo. It retries timeouts and 5xx errors with backoff, up to a limit, and reports any other error.
  3. Adds numbers and other services to the project.

Give people access

To give your staff or your customer's users access to a project, add them in the Enfonica Console. For the roles that you can give them, see Access control.

What's next