> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomobile.ma/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Create, update, search, and manage contacts

<Info>
  **Base path: `/contact`**
</Info>

## Types

<Accordion title="Type Definitions">
  ```typescript theme={null}
  // ============ 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;
  }
  ```
</Accordion>

### Get all contacts

**Searchable fields:** firstName, lastName, fullName, primaryPhone, primaryEmail

**Sortable fields:** firstName, lastName, primaryPhone, primaryEmail, createdAt

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET https://api.gomobile.ma/api/contact/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl -X DELETE https://api.gomobile.ma/api/contact/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  ...
}
```