README

The ConvertKit PHP SDK provides convinient access to the ConvertKit API from applications written in the PHP language.

It includes a pre-defined set of methods for interacting with the API.

Version Guidance

Refer to this guide for changes when upgrading to the v2 SDK.

Composer

You can install this PHP SDK via Composer. Run the following command:

composer require convertkit/convertkitapi

To use the PHP SDK, use Composer's autoload:

require_once 'vendor/autoload.php';

Dependencies

The PHP SDK require the following extensions in order to work properly:

curl, although you can use your own non-cURL client if you prefer
json
mbstring (Multibyte String)

If you use Composer, these dependencies should be handled automatically.

Getting Started

2.x (v4 API, OAuth, PHP 8.0+)

First, register your OAuth application in the OAuth Applications section at https://app.convertkit.com/account_settings/advanced_settings.

Using the supplied Client ID and secret, redirect the user to ConvertKit to grant your application access to their ConvertKit account.

// Require the autoloader (if you're using a PHP framework, this may already be done for you).
require_once 'vendor/autoload.php';

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
    clientID: '<your_oauth_client_id>',
    clientSecret: '<your_oauth_client_secret>'
);

// Redirect to begin the OAuth process.
header('Location: '.$api->get_oauth_url('<your_redirect_uri>'));

Once the user grants your application access to their ConvertKit account, they'll be redirected to your Redirect URI with an authorization code. For example:

your-redirect-uri?code=<auth_code>

At this point, your application needs to exchange the authorization code for an access token and refresh token.

$result = $api->get_access_token(
    authCode: '<auth_code>',
    redirectURI: '<your_redirect_uri>'
);

$result is an array comprising of:

access_token: The access token, used to make authenticated requests to the API
refresh_token: The refresh token, used to fetch a new access token once the current access token has expired
created_at: When the access token was created
expires_in: The number of seconds from created_at that the access token will expire

Once you have an access token, re-initialize the API class with it:

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
    clientID: '<your_oauth_client_id>',
    clientSecret: '<your_oauth_client_secret>',
    accessToken: '<your_access_token>'
);

To refresh an access token:

$result = $api->refresh_token(
    refreshToken: '<your_refresh_token>',
    redirectURI: '<your_redirect_uri>'
);

$result is an array comprising of:

access_token: The access token, used to make authenticated requests to the API
refresh_token: The refresh token, used to fetch a new access token once the current access token has expired
created_at: When the access token was created
expires_in: The number of seconds from created_at that the access token will expire

Once you have refreshed the access token i.e. obtained a new access token, re-initialize the API class with it:

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
    clientID: '<your_oauth_client_id>',
    clientSecret: '<your_oauth_client_secret>',
    accessToken: '<your_new_access_token>'
);

API requests may then be performed:

$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@convertkit.com');

To determine whether a new entity / relationship was created, or an existing entity / relationship updated, inspect the HTTP code of the last request:

$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@convertkit.com');
$code = $api->getResponseInterface()->getStatusCode(); // 200 OK if e.g. a subscriber already added to the specified form, 201 Created if the subscriber added to the specified form for the first time.

The PSR-7 response can be fetched and further inspected, if required - for example, to check if a header exists:

$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@convertkit.com');
$api->getResponseInterface()->hasHeader('Content-Length'); // Check if the last API request included a `Content-Length` header

1.x (v3 API, API Key and Secret, PHP 7.4+)

Get your ConvertKit API Key and API Secret here and set it somewhere in your application.

// Require the autoloader (if you're using a PHP framework, this may already be done for you).
require_once 'vendor/autoload.php';

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API('<your_public_api_key>', '<your_secret_api_key>');

Handling Errors

The ConvertKit PHP SDK uses Guzzle for all HTTP API requests. Errors will be thrown as Guzzle's ClientException (for 4xx errors), or ServerException (for 5xx errors).

try {
    $forms = $api->add_subscriber_to_form('invalid-form-id');
} catch (GuzzleHttp\Exception\ClientException $e) {
    // Handle 4xx client errors.
    die($e->getMessage());
} catch (GuzzleHttp\Exception\ServerException $e) {
    // Handle 5xx server errors.
    die($e->getMessage());
}

For a more detailed error message, it's possible to fetch the API's response when a ClientException is thrown:

// Errors will be thrown as Guzzle's ClientException or ServerException.
try {
    $forms = $api->form_subscribe('invalid-form-id');
} catch (GuzzleHttp\Exception\ClientException $e) {
    // Handle 4xx client errors.
    // For ClientException, it's possible to inspect the API's JSON response
    // to output an error or handle it accordingly.
    $error = json_decode($e->getResponse()->getBody()->getContents());
    die($error->message); // e.g. "Entity not found".
} catch (GuzzleHttp\Exception\ServerException $e) {
    // Handle 5xx server errors.
    die($e->getMessage());
}

Documentation

See the PHP SDK docs

Contributing

See our contributor guide for setting up your development environment, testing and submitting a PR.

For ConvertKit, refer to the deployment guide on how to publish a new release.

convertkit / convertkitapi

Maintainers

Details