https://github.com/kit/convertkitsdk-php
Kit official PHP SDK
https://github.com/kit/convertkitsdk-php
Last synced: 4 months ago
JSON representation
Kit official PHP SDK
- Host: GitHub
- URL: https://github.com/kit/convertkitsdk-php
- Owner: Kit
- Created: 2016-09-08T20:50:37.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2026-03-03T11:33:43.000Z (4 months ago)
- Last Synced: 2026-03-03T12:53:10.542Z (4 months ago)
- Language: PHP
- Homepage:
- Size: 920 KB
- Stars: 21
- Watchers: 3
- Forks: 24
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# Kit SDK PHP
The Kit PHP SDK provides convinient access to the Kit API from applications written in the PHP language.
It includes a pre-defined set of methods for interacting with the API.
## Version Guidance
| SDK Version | API Version | API Authentication | PHP Version |
|-------------|-------------|--------------------|--------------|
| 1.x | v3 | API Key and Secret | 7.4+ |
| 2.x | v4 | OAuth | 8.0+ |
| 2.2+ | v4 | API Key | 8.0+ |
Refer to [this guide](MIGRATION.md) for changes when upgrading to the v2 SDK.
## Composer
You can install this PHP SDK via [Composer](http://getcomposer.org/). Run the following command:
```bash
composer require convertkit/convertkitapi
```
To use the PHP SDK, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading):
```php
require_once 'vendor/autoload.php';
```
## Dependencies
The PHP SDK require the following extensions in order to work properly:
- [`curl`](https://secure.php.net/manual/en/book.curl.php), although you can use your own non-cURL client if you prefer
- [`json`](https://secure.php.net/manual/en/book.json.php)
- [`mbstring`](https://secure.php.net/manual/en/book.mbstring.php) (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.kit.com/account_settings/advanced_settings.
Using the supplied Client ID and secret, redirect the user to Kit to grant your application access to their Kit account.
```php
// 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: '',
clientSecret: ''
);
// Redirect to begin the OAuth process.
header('Location: '.$api->get_oauth_url(''));
```
Once the user grants your application access to their Kit account, they'll be redirected to your Redirect URI with an authorization code. For example:
`your-redirect-uri?code=`
At this point, your application needs to exchange the authorization code for an access token and refresh token.
```php
$result = $api->get_access_token(
authCode: '',
redirectURI: ''
);
```
`$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:
```php
// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
clientID: '',
clientSecret: '',
accessToken: ''
);
```
To refresh an access token:
```php
$result = $api->refresh_token(
refreshToken: '',
redirectURI: ''
);
```
`$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:
```php
// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
clientID: '',
clientSecret: '',
accessToken: ''
);
```
API requests may then be performed:
```php
$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@kit.com');
```
To determine whether a new entity / relationship was created, or an existing entity / relationship updated, inspect the HTTP code of the last request:
```php
$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@kit.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:
```php
$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@kit.com');
$api->getResponseInterface()->hasHeader('Content-Length'); // Check if the last API request included a `Content-Length` header
```
### 2.2+ (v4 API, API Key, PHP 8.0+)
Get your Kit API Key and API Secret [here](https://app.kit.com/account_settings/developer_settings) and set it somewhere in your application.
```php
// 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(
apiKey: ''
);
```
### 1.x (v3 API, API Key and Secret, PHP 7.4+)
Get your Kit API Key and API Secret [here](https://app.kit.com/account_settings/developer_settings) and set it somewhere in your application.
```php
// 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('', '');
```
## Handling Errors
The Kit 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).
```php
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:
```php
// 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](./docs/classes/ConvertKit_API/ConvertKit_API.md)
## Contributing
See our [contributor guide](CONTRIBUTING.md) for setting up your development environment, testing and submitting a PR.
For Kit, refer to the [deployment guide](DEPLOYMENT.md) on how to publish a new release.