Contacts

Base path: /contact

Types

Type Definitions

// ============ Enums ============

type Gender = 'male' | 'female';

type SortOrder = 'asc' | 'desc';

// ============ Request Types ============

interface CreateContactRequest {
  firstName?: string;           // 2-64 characters
  lastName?: string;            // 1-64 characters
  fullName?: string;            // 3-64 characters
  primaryEmail?: string;        // valid email
  primaryPhone: string;         // 3-20 characters (required)
  address?: string;             // 3-256 characters
  city?: string;                // 3-64 characters
  state?: string;               // 3-64 characters
  zip?: string;                 // 3-64 characters
  occupation?: string;          // 3-64 characters
  preferredChannel?: string;    // 3-64 characters
  customAttributes?: Record<string, unknown>;
  gender?: Gender;
  channels?: string[];
}

interface UpdateContactRequest {
  firstName?: string;           // 2-64 characters
  lastName?: string;            // 1-64 characters
  fullName?: string;            // 3-64 characters
  primaryEmail?: string;
  primaryPhone?: string;        // 3-20 characters
  address?: string;             // 3-256 characters
  city?: string;                // 3-64 characters
  state?: string;               // 3-64 characters
  zip?: string;                 // 3-64 characters
  occupation?: string;          // 3-64 characters
  preferredChannel?: string;    // 3-64 characters
  customAttributes?: Record<string, unknown>;
  gender?: Gender;
  channels?: string[];
}

interface UpsertContactRequest {
  data: CreateContactRequest[];
}

// ============ Query Parameters ============

interface ContactQueryParams {
  page?: number;                // default: 1, min: 1
  limit?: number;               // default: 20, max: 100
  search?: string;              // max 100 characters
  sortBy?: string;              // firstName, lastName, primaryPhone, primaryEmail, createdAt
  sortOrder?: SortOrder;        // default: 'desc'
}

// ============ Response Types ============

interface ContactResponse {
  id: string;
  organizationId: string;
  firstName: string | null;
  lastName: string | null;
  fullName: string | null;
  primaryEmail: string | null;
  primaryPhone: string;
  address: string | null;
  city: string | null;
  state: string | null;
  zip: string | null;
  occupation: string | null;
  preferredChannel: string | null;
  gender: Gender | null;
  channels: ContactChannel[];   // JSONB array
  createdAt: string;            // ISO date
  updatedAt: string;            // ISO date
  deletedAt: string | null;     // ISO date (soft delete)
  createdBy: string | null;     // User UUID
  updatedBy: string | null;     // User UUID
  deletedBy: string | null;     // User UUID
}

interface ContactChannel {
  type: string;                 // 'phone' | 'email' | 'whatsapp' | etc.
  value: string;
  isPrimary: boolean;
}

interface ContactCustomAttribute {
  name: string;
  displayName: string;
  description: string | null;
  type: string;
  value: unknown;
  isLocked: boolean;
}

interface ContactWithAttributesResponse extends ContactResponse {
  customAttributes: ContactCustomAttribute[];
}

interface PaginationMeta {
  page: number;
  limit: number;
  total: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
}

interface ContactListResponse {
  data: ContactResponse[];
  meta: PaginationMeta;
}

Get all contacts

Searchable fields: firstName, lastName, fullName, primaryPhone, primaryEmail Sortable fields: firstName, lastName, primaryPhone, primaryEmail, createdAt

curl -X GET https://api.gomobile.ma/api/contact?page=1&limit=20&search=john&sortBy=createdAt&sortOrder=desc \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "660e8400-e29b-41d4-a716-446655440001",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "primaryEmail": "john@example.com",
      "primaryPhone": "+212612345678",
      "address": "123 Main St",
      "city": "Casablanca",
      "state": "Casablanca-Settat",
      "zip": "20000",
      "occupation": "Engineer",
      "preferredChannel": "phone",
      "gender": "male",
      "channels": [],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Get contact by ID

curl -X GET https://api.gomobile.ma/api/contact/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "primaryEmail": "john@example.com",
  "primaryPhone": "+212612345678",
  "address": "123 Main St",
  "city": "Casablanca",
  "state": "Casablanca-Settat",
  "zip": "20000",
  "occupation": "Engineer",
  "preferredChannel": "phone",
  "gender": "male",
  "channels": [],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "customAttributes": [
    {
      "name": "company_size",
      "displayName": "Company Size",
      "description": "Number of employees",
      "type": "number",
      "value": 100,
      "isLocked": false
    }
  ]
}

Create a new contact

curl -X POST https://api.gomobile.ma/api/contact \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "primaryEmail": "john@example.com",
  "primaryPhone": "+212612345678",
  "city": "Casablanca",
  "gender": "male",
  "customAttributes": {
    "age": 30,
    "interests": ["tech"]
  }
}
'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "primaryEmail": "john@example.com",
  "primaryPhone": "+212612345678",
  "address": null,
  "city": "Casablanca",
  "state": null,
  "zip": null,
  "occupation": null,
  "preferredChannel": null,
  "gender": "male",
  "channels": [],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Bulk upsert contacts

curl -X POST https://api.gomobile.ma/api/contact/upsert \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "data": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "primaryPhone": "+212612345678"
    },
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "primaryPhone": "+212612345679"
    }
  ]
}
'

Update contact

curl -X PUT https://api.gomobile.ma/api/contact/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
  "firstName": "Jonathan",
  "occupation": "Senior Engineer"
}
'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "firstName": "Jonathan",
  "lastName": "Doe",
  "fullName": "John Doe",
  "primaryEmail": "john@example.com",
  "primaryPhone": "+212612345678",
  "address": null,
  "city": "Casablanca",
  "state": null,
  "zip": null,
  "occupation": "Senior Engineer",
  "preferredChannel": null,
  "gender": "male",
  "channels": [],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z"
}

Delete contact

curl -X DELETE https://api.gomobile.ma/api/contact/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  ...
}

Introduction

Getting Started

Core Concepts

Features

Agent Studio

Guides

Types

Get all contacts

Get contact by ID

Create a new contact

Bulk upsert contacts

Update contact

Delete contact

​Types

​Get all contacts

​Get contact by ID

​Create a new contact

​Bulk upsert contacts

​Update contact

​Delete contact

Types

Get all contacts

Get contact by ID

Create a new contact

Bulk upsert contacts

Update contact

Delete contact