Skip to main content

​
Installation

Get started by installing the Ortto SDK via Composer.
1

Install via Composer

Install the package using Composer:
composer require phpdevkits/ortto-sdk
The package will be automatically discovered by Laravel.
2

Publish Configuration

Publish the configuration file to your Laravel application:
php artisan vendor:publish --provider="PhpDevKits\Ortto\OrttoServiceProvider"
This creates config/ortto.php in your Laravel application.
3

Configure API Credentials

Add your Ortto API credentials to your .env file:
ORTTO_API_KEY=your-api-key-here
ORTTO_API_URL=https://api.ap3api.com/v1
Get your API key from your Ortto account settings under API > Custom API.

​
Configuration

​
API Regions

Ortto uses region-specific endpoints. Set the correct API URL for your account region: 
ORTTO_API_URL=https://api.ap3api.com/v1
Use this for most Ortto accounts (default).

​
Configuration File

The published configuration file (config/ortto.php) looks like this: 
return [

    'api_key' => env('ORTTO_API_KEY', ''),

    'url' => env('ORTTO_API_URL', 'https://api.eu.ap3api.com/v1'),

    'suppression_list_field_id' => env('ORTTO_SUPPRESSION_LIST_FIELD_ID', 'str::email'),

];
The url field should be set to the full API endpoint URL including /v1 for your region.

​
Your First Request

Let’s create your first contact in Ortto! 
use PhpDevKits\Ortto\Facades\Ortto;
use PhpDevKits\Ortto\Enums\PersonField;
use PhpDevKits\Ortto\Enums\MergeStrategy;

$response = Ortto::send(
    new MergePeople(
        people: [
            [
                'fields' => [
                    'str::email' => '[email protected]',
                    'str::first' => 'John',
                    'str::last' => 'Doe',
                ]
            ]
        ],
        mergeBy: [PersonField::Email],
        mergeStrategy: MergeStrategy::OverwriteExisting,
    )
);

// Check the response
if ($response->successful()) {
    $personId = $response->json('people.0.person_id');
    $status = $response->json('people.0.status'); // 'created' or 'merged'
}
Success! You’ve created your first contact in Ortto using the SDK.

​
Common Operations

Here are some common operations you’ll perform with the SDK: 
use PhpDevKits\Ortto\Facades\Ortto;
use PhpDevKits\Ortto\Requests\Person\MergePeople;
use PhpDevKits\Ortto\Enums\PersonField;
use PhpDevKits\Ortto\Enums\MergeStrategy;

$response = Ortto::send(
    new MergePeople(
        people: [
            [
                'fields' => [
                    'str::email' => '[email protected]',
                    'str::first' => 'Jane',
                    'str::last' => 'Smith',
                    'str::phone' => '+1234567890',
                    'bol::p' => true, // Email permission
                ]
            ]
        ],
        mergeBy: [PersonField::Email],
        mergeStrategy: MergeStrategy::OverwriteExisting,
    )
);

use PhpDevKits\Ortto\Facades\Ortto;
use PhpDevKits\Ortto\Requests\Person\GetPeople;

$response = Ortto::send(
    new GetPeople(
        fields: ['str::email', 'str::first', 'str::last'],
        q: '[email protected]',
        limit: 1,
    )
);

$contacts = $response->json('contacts');

use PhpDevKits\Ortto\Facades\Ortto;
use PhpDevKits\Ortto\Requests\Person\GetPersonActivities;
use PhpDevKits\Ortto\Enums\ActivityTimeframe;

$response = Ortto::send(
    new GetPersonActivities(
        personId: '0069061b5bda4060a5765300',
        timeframe: ActivityTimeframe::Last30Days,
        limit: 50,
    )
);

$activities = $response->json('activities');

use PhpDevKits\Ortto\Facades\Ortto;
use PhpDevKits\Ortto\Requests\Audience\GetAudiences;

$response = Ortto::send(
    new GetAudiences(
        searchTerm: 'subscribers',
        limit: 20,
    )
);

$audiences = $response->json();

​
Using with Testing

The SDK is built on Saloon, which provides excellent testing capabilities with MockClient: 
use PhpDevKits\Ortto\Ortto;
use PhpDevKits\Ortto\Requests\Person\MergePeople;
use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;

test('creates contact in ortto', function () {
    $mockClient = new MockClient([
        MergePeople::class => MockResponse::make([
            'people' => [
                [
                    'person_id' => '123456',
                    'status' => 'created',
                ]
            ]
        ]),
    ]);

    $ortto = new Ortto();

    $response = $ortto
        ->withMockClient($mockClient)
        ->send(new MergePeople(/* ... */));

    expect($response->json('people.0.status'))->toBe('created');
});
MockClient can auto-record real API responses as fixtures for easier test setup!

​
Next Steps

People API

Learn about managing contacts in Ortto.

Activities API

Track and retrieve customer activities.

Audiences API

Manage audience subscriptions.

Testing Guide

Learn how to test with the SDK.

​
Troubleshooting

Problem: Your API key is invalid or missing.Solution:
  • Verify ORTTO_API_KEY is set in .env
  • Check the API key in your Ortto account settings
  • Ensure no extra spaces or quotes around the key
Problem: Wrong API endpoint URL or person doesn’t exist.Solution:
  • Verify ORTTO_API_URL is set to the correct regional endpoint
  • Ensure URL includes /v1 at the end
  • For person endpoints, ensure the person_id is valid
Problem: Invalid request parameters or field IDs.Solution:
  • Check Ortto field format: type::field (e.g., str::email)
  • Custom fields use: type:cm:field (e.g., str:cm:job-title)
  • Ensure required parameters are provided
Problem: Too many requests to certain endpoints.Solution:
  • Some endpoints have rate limits (e.g., 1 req/sec for activities)
  • Implement exponential backoff for retries
  • Use async mode for bulk operations
Need more help? Check the API Reference or Ortto’s official documentation.