Usage

All services follow the same pattern: inject the service and call its methods. Methods accept/return associative arrays matching the One Page CRM API schemas.

Dependency injection

use Drupal\one_page_crm_api\Service\ContactsService;

public function __construct(
  private readonly ContactsService $contacts,
) {}

public static function create(ContainerInterface $container): static {
  return new static($container->get('one_page_crm_api.contacts'));
}

Error handling

API errors throw GuzzleHttp\Exception\RequestException:

use GuzzleHttp\Exception\RequestException;

try {
  $result = $contacts->getContact($id);
}
catch (RequestException $e) {
  $status = $e->hasResponse()
    ? $e->getResponse()->getStatusCode()
    : 0;
  \Drupal::logger('my_module')->error(
    'API error @status: @msg',
    ['@status' => $status, '@msg' => $e->getMessage()]
  );
}

Contacts

$contacts = \Drupal::service('one_page_crm_api.contacts');

// List
$result = $contacts->getContacts(['per_page' => 20, 'page' => 1, 'search' => 'Acme']);

// Get
$result = $contacts->getContact('CONTACT_ID');

// Create
$result = $contacts->createContact([
  'first_name' => 'Jane',
  'last_name'  => 'Doe',
  'emails'     => [['value' => 'jane@example.com', 'type' => 'work']],
]);

// Update
$result = $contacts->updateContact('CONTACT_ID', ['last_name' => 'Smith']);

// Delete
$contacts->deleteContact('CONTACT_ID');

Companies

$companies = \Drupal::service('one_page_crm_api.companies');

$result = $companies->getCompanies(['per_page' => 20]);
$result = $companies->getCompany('COMPANY_ID');
$result = $companies->createCompany(['name' => 'Acme Inc']);
$result = $companies->updateCompany('COMPANY_ID', ['name' => 'Acme Corp']);
$companies->deleteCompany('COMPANY_ID');

Deals

$deals = \Drupal::service('one_page_crm_api.deals');

$result = $deals->getDeals(['contact_id' => 'CONTACT_ID']);
$result = $deals->getDeal('DEAL_ID');
$result = $deals->createDeal([
  'contact_id' => 'CONTACT_ID',
  'name'       => 'Enterprise license',
  'amount'     => 15000,
  'stage'      => 'negotiation',
]);
$result = $deals->updateDeal('DEAL_ID', ['status' => 'won']);
$deals->deleteDeal('DEAL_ID');

Notes

$notes = \Drupal::service('one_page_crm_api.notes');

$result = $notes->getNotes(['contact_id' => 'CONTACT_ID']);
$result = $notes->getNote('NOTE_ID');
$result = $notes->createNote(['contact_id' => 'CONTACT_ID', 'text' => 'Met at conference']);
$result = $notes->updateNote('NOTE_ID', ['text' => 'Updated note']);
$notes->deleteNote('NOTE_ID');

Calls

$calls = \Drupal::service('one_page_crm_api.calls');

$result = $calls->getCalls(['contact_id' => 'CONTACT_ID']);
$result = $calls->getCall('CALL_ID');
$result = $calls->createCall([
  'contact_id'  => 'CONTACT_ID',
  'text'        => 'Discussed pricing',
  'call_result' => 'interested',
]);
$result = $calls->updateCall('CALL_ID', ['text' => 'Updated notes']);
$calls->deleteCall('CALL_ID');

Meetings

$meetings = \Drupal::service('one_page_crm_api.meetings');

$result = $meetings->getMeetings(['contact_id' => 'CONTACT_ID']);
$result = $meetings->getMeeting('MEETING_ID');
$result = $meetings->createMeeting([
  'contact_id'       => 'CONTACT_ID',
  'text'             => 'Product demo',
  'meeting_time_int' => time(),
  'place'            => 'Conference room',
]);
$result = $meetings->updateMeeting('MEETING_ID', ['text' => 'Rescheduled']);
$meetings->deleteMeeting('MEETING_ID');

Actions

$actions = \Drupal::service('one_page_crm_api.actions');

$result = $actions->getActions(['contact_id' => 'CONTACT_ID']);
$result = $actions->getAction('ACTION_ID');
$result = $actions->createAction([
  'contact_id' => 'CONTACT_ID',
  'text'       => 'Follow up call',
  'status'     => 'asap',
]);
$result = $actions->updateAction('ACTION_ID', ['text' => 'Updated'], ['done' => 'true']);
$actions->deleteAction('ACTION_ID');

// Special operations
$actions->markAsDone('ACTION_ID');
$actions->undoCompletion('ACTION_ID');
$actions->promote('ACTION_ID');
$actions->revertPromotion('ACTION_ID');
$actions->unassign('ACTION_ID');
$actions->swap('ACTION_ID', ['target_action_id' => 'OTHER_ID']);

Attachments

$attachments = \Drupal::service('one_page_crm_api.attachments');

// Get S3 upload form data
$result = $attachments->getS3Form('CONTACT_ID');

// Create (after uploading to S3)
$result = $attachments->createAttachment([
  'contact_id' => 'CONTACT_ID',
  'name'       => 'document.pdf',
  'key'        => 's3-key',
  'size'       => 1048576,
]);

// Update (PATCH)
$result = $attachments->updateAttachment('ATTACHMENT_ID', [
  'attachment' => ['custom_filename' => 'renamed.pdf'],
]);

$attachments->deleteAttachment('ATTACHMENT_ID');
$attachments->pin('ATTACHMENT_ID');
$attachments->unpin('ATTACHMENT_ID');

Predefined actions

$service = \Drupal::service('one_page_crm_api.predefined_actions');

$result = $service->getPredefinedActions();
$result = $service->getPredefinedAction('ID');
$result = $service->createPredefinedAction(['text' => 'Send proposal']);
$result = $service->updatePredefinedAction('ID', ['text' => 'Updated']);
$service->deletePredefinedAction('ID');

Predefined items

$service = \Drupal::service('one_page_crm_api.predefined_items');

$result = $service->getPredefinedItems();
$result = $service->getPredefinedItem('ID');
$result = $service->createPredefinedItem(['name' => 'Widget', 'amount' => 99.99]);
$result = $service->updatePredefinedItem('ID', ['amount' => 149.99]);
$service->deletePredefinedItem('ID');

Predefined item groups

$service = \Drupal::service('one_page_crm_api.predefined_item_groups');

$result = $service->getPredefinedItemGroups();
$result = $service->getPredefinedItemGroup('ID');
$result = $service->createPredefinedItemGroup(['name' => 'Services']);
$service->deletePredefinedItemGroup('ID');

Relationship types, custom fields, company fields, deal fields

Standard CRUD services following the same pattern:

$service = \Drupal::service('one_page_crm_api.relationship_types');
$service = \Drupal::service('one_page_crm_api.custom_fields');
$service = \Drupal::service('one_page_crm_api.company_fields');
$service = \Drupal::service('one_page_crm_api.deal_fields');

Read-only services

Call results

$result = \Drupal::service('one_page_crm_api.call_results')->getCallResults();

Filters

$filters = \Drupal::service('one_page_crm_api.filters');
$result  = $filters->getFilters();
$result  = $filters->getFilter('FILTER_ID');

Countries

$result = \Drupal::service('one_page_crm_api.countries')->getCountries();

Lead sources

$sources = \Drupal::service('one_page_crm_api.lead_sources');
$result  = $sources->getLeadSources();
$result  = $sources->getLeadSource('SOURCE_ID');

Statuses

$statuses = \Drupal::service('one_page_crm_api.statuses');
$result   = $statuses->getStatuses();
$result   = $statuses->getStatus('STATUS_ID');

Pipelines

$pipelines = \Drupal::service('one_page_crm_api.pipelines');
$result    = $pipelines->getPipelines();
$result    = $pipelines->getPipeline('PIPELINE_ID');

Notifications

$notifications = \Drupal::service('one_page_crm_api.notifications');

$result = $notifications->getNotifications(['page' => 1]);
$result = $notifications->getNotification('NOTIFICATION_ID');
$notifications->markAsRead('NOTIFICATION_ID');
$notifications->markAllAsRead();

Webhooks

$webhooks = \Drupal::service('one_page_crm_api.webhooks');

$result = $webhooks->getWebhooks();
$result = $webhooks->getWebhook('WEBHOOK_ID');
$webhooks->deleteWebhook('WEBHOOK_ID');

Users

$users = \Drupal::service('one_page_crm_api.users');

$result = $users->getUsers();
$result = $users->getUser('USER_ID');
$result = $users->updateUser('USER_ID', ['first_name' => 'Updated']);