Get companies

Retrieve a list of companies managed by your agency, including their ID, name, owner's name, status (active or inactive), number of running campaigns, and number of connected accounts.

Use this endpoint to get company IDs for other requests. Refer to the related /companies endpoints.

Request

Endpoint

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

Headers

x-api-key: {YOUR_API_KEY}

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

Parameters

Parameter	Required	Type	Description
active	No	boolean	Whether to return only active or inactive comapnies
page	No	integer	Requested results page (1-based)

Request samples

Retrieve first page of companies

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/agency/companies" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def get_companies():
  url = "https://api.woodpecker.co/rest/v2/agency/companies"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }
  
  response = requests.get(url, headers=headers)
  if response.status_code == 200:
    return response.json()
  else:
    raise Exception(f"GET request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    data = get_companies()
    print("GET 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) {
    try {
      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)
        .GET()
        .build();

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

Node.js

const axios = require('axios');

async function getCompanies() {
  const url = 'https://api.woodpecker.co/rest/v2/agency/companies';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}'
  };

  try {
    const response = await axios.get(url, { headers });
    console.log('GET response:', response.data);
  } catch (error) {
    console.error('GET request failed:', error.response ? error.response.status : error.message);
  }
}

(async () => {
  await getCompanies();
})();

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => ['x-api-key' => getenv('WOODPECKER_API_KEY')],
]);

try {
  $response = $client->get('agency/companies');
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Retrieve a second page of active companies

cURL

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/agency/companies?active=true&page=2" \
  --header "x-api-key: {YOUR_API_KEY}"

Python

import requests

def get_companies():
  url = "https://api.woodpecker.co/rest/v2/agency/companies?active=true&page=2"
  headers = {
    "x-api-key": "{YOUR_API_KEY}"
  }
  
  response = requests.get(url, headers=headers)
  if response.status_code == 200:
    return response.json()
  else:
    raise Exception(f"GET request failed: {response.status_code}, {response.text}")

if __name__ == "__main__":
  try:
    data = get_companies()
    print("GET 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?active=true&page=2";

  public static void main(String[] args) {
    try {
      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)
        .GET()
        .build();

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

Node.js

const axios = require('axios');

async function getCompanies() {
  const url = 'https://api.woodpecker.co/rest/v2/agency/companies?active=true&page=2';
  const headers = {
    'x-api-key': '{YOUR_API_KEY}'
  };

  try {
    const response = await axios.get(url, { headers });
    console.log('GET response:', response.data);
  } catch (error) {
    console.error('GET request failed:', error.response ? error.response.status : error.message);
  }
}

(async () => {
  await getCompanies();
})();

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.woodpecker.co/rest/v2/',
  'headers'  => ['x-api-key' => getenv('WOODPECKER_API_KEY')],
]);

try {
  $response = $client->get('agency/companies', [
    'query' => [
      'active' => 'true',
      'page'   => 2,
    ],
  ]);
  echo $response->getStatusCode(), "\n";
  echo $response->getBody(), "\n";
} catch (RequestException $e) {
  echo "Error: ", $e->getMessage(), "\n";
  if ($e->hasResponse()) {
    echo $e->getResponse()->getBody(), "\n";
  }
}

Response

Response examples

200

A list of clients companies. If there are no clients companies, content will be an empty array.

{
  "content": [
    {
      "id": 12345678,
      "name": "Dunmore High School",
      "owner": "Jim Halpert",
      "active": true,
      "running_campaigns": 2,
      "email_slots": 2,
      "linkedin_slots": 1
    },
    {
      "id": 12345679,
      "name": "Beets Beets Beets",
      "owner": "Dwight Schrute",
      "active": false,
      "running_campaigns": 0,
      "email_slots": 0,
      "linkedin_slots": 0
    }
  ],
  "pagination_data": {
    "total_elements": 2,
    "total_pages": 1,
    "current_page_number": 1,
    "page_size": 50
  }
}

Body schema

Field	Type	Description
content	array[object]	Array of company objects
└─[].id	integer	Company ID
└─[].name	string	Company name
└─[].owner	string	Owner of the company, one of the team members
└─[].active	boolean	Whether this company is active or not
└─[].running_campaigns	integer	Number of campaigns running for that specific company
└─[].email_slots	integer	Number of connected emails accounts
└─[].linkedin_slots	integer	Number of connected LinkedIn accounts
pagination_data	object	Pagination information. See the pagination section

400

Invalid request parameters or malformed request syntax.

{
  "title": "Bad request",
  "status": 400,
  "detail": "Page parameter must be a positive number",
  "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": "2024-11-05 17:55:02"
}

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

Unexpected error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2024-11-05 17:55:02"
}

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

Pagination

The response body contains pagination details. It will support you in navigating through larger datasets.

Use page parameter to view a specific page.

info

Each page contains up to 50 companies

{
  "content": [],
  "pagination_data": {
    "total_elements": 300,
    "total_pages": 6,
    "current_page_number": 2,
    "page_size": 50
  }
}

Field	Type	Description
pagination_data	object	Pagination information
└─total_elements	integer	Total number of companies
└─total_pages	integer	Total number of available pages
└─current_page_number	integer	Current page number (1-based)
└─page_size	integer	Maximum number of items per page