Create companies

Create new client accounts under your agency account, each with its own prospect database, campaigns, and team access.

Each company created via API will automatically have an API key generated. Use /companies/{company_id}/api_keys to fetch it.

Request

The user making the request will automatically become the owner of the company. The request follows an all-or-none rule - if any company in the request is invalid (e.g., the name is already taken), none will be created.

warning

Adding a new client account comes with a fee, and you'll be charged periodically for each active account. See the pricing page for more details.

Endpoint

POST https://api.woodpecker.co/rest/v2/agency/companies

Headers

x-api-key: {YOUR_API_KEY}
Content-Type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Body

{
  "companies": [
    {
      "name": "My first client"
    },
    {
      "name": "My second client"
    }
  ]
}

info

You can add up to 10 companies in one request

Body schema

Field	Type	Required	Description
companies	array[object]	Yes	A list of companies to be created
└─companies[].name	string	Yes	Name of a company

Request sample

Create new companies

cURL

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/agency/companies" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "companies": [
      {
        "name": "My first client"
      },
      {
        "name": "My second client"
      }
    ]
  }'

Python

import requests

def create_companies(companies):
  url = "https://api.woodpecker.co/rest/v2/agency/companies"
  headers = {
    "x-api-key": "{YOUR_API_KEY}",
    "Content-Type": "application/json"
  }
  data = {
    "companies": companies
  }
  
  response = requests.post(url, headers=headers, json=data)
  if response.status_code == 201:
    return response.json()
  else:
    raise Exception(f"POST request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    companies = [
      {"name": "My first client"},
      {"name": "My second client"}
    ]
    data = create_companies(companies)
    print("POST response:", data)
  except Exception as e:
    print("Error:", e)

Java

public class WoodpeckerApiClient {
  private static final String API_KEY = "{YOUR_API_KEY}";
  private static final String URL = "https://api.woodpecker.co/rest/v2/agency/companies";

  public static void main(String[] args) {
    createCompanies();
  }

  public static void createCompanies() {
    try {
      String jsonData = "{"
        + "\"companies\": ["
        + "{ \"name\": \"My first client\" },"
        + "{ \"name\": \"My second client\" }"
        + "]"
        + "}";
      java.net.http.HttpClient client = java.net.http.HttpClient.newHttpClient();
      java.net.http.HttpRequest request = java.net.http.HttpRequest.newBuilder()
        .uri(new java.net.URI(URL))
        .header("x-api-key", API_KEY)
        .header("Content-Type", "application/json")
        .POST(java.net.http.HttpRequest.BodyPublishers.ofString(jsonData))
        .build();

      java.net.http.HttpResponse<String> response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() == 201) {
        System.out.println("POST response: " + response.body());
      } else {
        System.err.println("POST request failed: " + response.statusCode());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Node.js

const axios = require('axios');

async function createCompanies(companies) {
  const url = 'https://api.woodpecker.co/rest/v2/agency/companies';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}',
    'Content-Type': 'application/json'
  };
  const data = { companies: companies };

  try {
    const response = await axios.post(url, data, { headers });
    if (response.status === 201) {
      console.log('POST response:', response.data);
    } else {
      console.error('POST request failed:', response.status);
    }
  } catch (error) {
    console.error('POST request failed:', error.response ? error.response.status : error.message);
  }
}

(async () => {
  const companies = [
    { name: "My first client" },
    { name: "My second client" }
  ];
  await createCompanies(companies);
})();

Response

Response examples

201

A list of created companies

{
  "companies": [
    {
      "id": 98764,
      "name": "My first client",
      "owner": "Michael Scott",
      "active": true
    },
    {
      "id": 98765,
      "name": "My second client",
      "owner": "Michael Scott",
      "active": true
    }
  ]
}

Body schema

Field	Type	Description
companies	array[object]	An array of created companies
└─id	integer	Company ID
└─name	string	Company name
└─owner	string	Owner of the company, the user making the request
└─active	boolean	Indicates whether this company is active or not. When creating a company always true

400

Invalid request parameters or malformed request syntax.

{
  "title": "Bad request",
  "status": 400,
  "detail": "Value of companies is incorrect." | "Requested company name must not be blank." | "Requested company names are not unique. Found duplicate: duplicated name" | "You can create up to 10 companies with one request.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

401

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

404

Please review the request URL.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

422

Please review the request URL.

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Company with given name already exist in agency: company name",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC

500

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
title	string	A short title describing the error
status	integer	The HTTP status code
detail	string	A detailed message explaining the error
timestamp	string	The timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC