Introduction

The following endpoints provide various functionalities for managing clients and contacts within the Happyoffer API. These endpoints allow users to perform operations such as retrieving, creating, updating, and storing client and contact information. Each request ensures that the company_id of the user matches the company_id associated with the client or contact being accessed or modified, maintaining data integrity and security. By using these endpoints, companies can efficiently manage their client relationships and contact details.

GET/api/clients

Get all clients

Retrieve a list of all clients associated with the authenticated user’s company. This endpoint ensures that users only access clients that belong to their assigned company.

Example response

{
    "data": [
        {
            "id": "XXX",
            "attributes": {
                "user_id": null,
                "external_client_id": null,
                "company_name": null,
                "address": null,
                "house_number": null,
                "zip_code": null,
                "country": null,
                "city": null,
                "phone_number": null,
                "website_url": null,
                "chamber_of_commerce_number": null,
                "email": null,
                "logo": null,
                "created_at": null,
                "updated_at": null,
            },
            "relationships": {
                "user": {
                    "id": null,
                    "full_name": null,
                }
            }
        },
        // More clients
    ]
}
GET/api/clients/{client_id}

Get client by id

This endpoint retrieves a single client based on the provided client ID. The request checks if the company_id of the client matches the company_id of the user performing the request.

Parameters

  • client_id (string): The unique identifier of the client being retrieved.

Example response

{
  "id": "1",
  "attributes": {
    "user_id": "10",
    "company_name": "Example Company",
    "address": "123 Example Street",
    "house_number": "12A",
    "zip_code": "12345",
    "country": "USA",
    "city": "Example City",
    "phone_number": "+1-234-567-890",
    "website_url": "<https://www.example.com>",
    "chamber_of_commerce_number": "123456789",
    "email": "info@example.com",
    "logo": "<https://storage.example.com/logos/example.png>",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-02T12:00:00Z"
  },
  "relationships": {
    "user": {
      "id": "10",
      "full_name": "John Doe"
    }
  }
}

Notes

  • The company_id of the user performing the request must match the company_id associated with the client_id.
  • Ensure that the client_id provided in the request URL is valid and associated with your account.
  • Only a single client will be returned based on the provided client_id.
POST/api/clients

Create new client

This endpoint creates a new client for a specific company. The request checks if the company_id of the user performing the request matches the company_id associated with the new client being created.

Request body

The request body must include the following fields, where only the company_name and external_client_id is required:

  • company_name (string, required): The name of the company.
  • external_client_id (string|int, required): The external client id which refers to the client in your system.
  • address (string, optional): The address of the company.
  • house_number (string, optional): The house number of the company.
  • zip_code (string, optional): The zip code of the company's location.
  • country (string, optional): The country of the company.
  • city (string, optional): The city where the company is located.
  • phone_number (string, optional): The phone number of the company.
  • website_url (string, optional): The website URL of the company. Must be a valid URL format.
  • chamber_of_commerce_number (string, optional): The chamber of commerce number of the company.
  • email (string, optional): The email address of the company. Must be a valid email format.
  • logo (file, optional): The logo of the company.

Example request

{
  "company_name": "New Company",
  "address": "456 New Street",
  "house_number": "34B",
  "zip_code": "67890",
  "country": "USA",
  "city": "New City",
  "phone_number": "+1-123-456-7890",
  "website_url": "<https://www.newcompany.com>",
  "chamber_of_commerce_number": "987654321",
  "email": "contact@newcompany.com",
  "logo": "<https://storage.example.com/logos/newcompany.png>"
}

Example response

{
  "id": "2",
  "attributes": {
    "user_id": "11",
    "company_name": "New Company",
    "address": "456 New Street",
    "house_number": "34B",
    "zip_code": "67890",
    "country": "USA",
    "city": "New City",
    "phone_number": "+1-123-456-7890",
    "website_url": "<https://www.newcompany.com>",
    "chamber_of_commerce_number": "987654321",
    "email": "contact@newcompany.com",
    "logo": "<https://storage.example.com/logos/newcompany.png>",
    "created_at": "2023-01-03T12:00:00Z",
    "updated_at": "2023-01-03T12:00:00Z"
  },
  "relationships": {
    "user": {
      "id": "11",
      "full_name": "Jane Smith"
    }
  }
}

Notes

  • The company_id of the user performing the request must match the company_id associated with the new client.
  • Ensure that all required fields are included in the request body.
  • The endpoint returns the newly created client upon successful validation and creation.
PATCH/api/clients/{client_id}

Update client by id

This endpoint updates an existing client based on the provided client ID. The request checks if the company_id of the client matches the company_id of the user performing the request.

Parameters

  • client_id (string): The unique identifier of the client being updated.

Request body

The request body must include the following fields:

  • company_name (string, required): The name of the company.
  • address (string, required): The address of the company.
  • house_number (string, required): The house number of the company.
  • zip_code (string, required): The zip code of the company's location.
  • country (string, required): The country of the company.
  • city (string, required): The city where the company is located.
  • phone_number (string, required): The phone number of the company.
  • website_url (string, optional): The website URL of the company. Must be a valid URL format.
  • chamber_of_commerce_number (string, optional): The chamber of commerce number of the company.
  • email (string, required): The email address of the company. Must be a valid email format.
  • logo (file, optional): The logo of the company.

Example request

{
  "company_name": "Updated Company",
  "address": "789 Updated Street",
  "house_number": "56C",
  "zip_code": "54321",
  "country": "USA",
  "city": "Updated City",
  "phone_number": "+1-321-654-0987",
  "website_url": "<https://www.updatedcompany.com>",
  "chamber_of_commerce_number": "123987456",
  "email": "contact@updatedcompany.com",
  "logo": "<https://storage.example.com/logos/updatedcompany.png>"
}

Example response

{
  "id": "1",
  "attributes": {
    "user_id": "10",
    "company_name": "Updated Company",
    "address": "789 Updated Street",
    "house_number": "56C",
    "zip_code": "54321",
    "country": "USA",
    "city": "Updated City",
    "phone_number": "+1-321-654-0987",
    "website_url": "<https://www.updatedcompany.com>",
    "chamber_of_commerce_number": "123987456",
    "email": "contact@updatedcompany.com",
    "logo": "<https://storage.example.com/logos/updatedcompany.png>",
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-04T12:00:00Z"
  },
  "relationships": {
    "user": {
      "id": "10",
      "full_name": "John Doe"
    }
  }
}

Notes

  • The company_id of the user performing the request must match the company_id associated with the client_id.
  • Ensure that the client_id provided in the request URL is valid and associated with your account.
  • All required fields must be included in the request body.
  • The endpoint returns the updated client upon successful validation and update.
GET/api/clients/{client_id}/contacts

Get all contacts for client

This endpoint retrieves all contacts associated with a specific client, identified by client_id. The request checks if the company_id of the client matches the company_id of the user performing the request.

Parameters

  • client_id (string): The unique identifier of the client for whom the contacts are being retrieved.

Example response

{
  "data": [
    {
      "id": "1",
      "attributes": {
        "client_id": "456",
        "firstname": "Jane",
        "lastname": "Doe",
        "gender": "Female",
        "email": "jane.doe@example.com",
        "email_confirmation": "jane.doe@example.com",
        "phone_number": "+1-987-654-3210",
        "note": "Met at the conference."
      }
    },
    {
      "id": "2",
      "attributes": {
        "client_id": "456",
        "firstname": "John",
        "lastname": "Smith",
        "gender": "Male",
        "email": "john.smith@example.com",
        "email_confirmation": "john.smith@example.com",
        "phone_number": "+1-123-456-7890",
        "note": "Follow up next week."
      }
    }
    // More contact objects
  ]
}

Notes

  • The company_id of the user performing the request must match the company_id associated with the client_id.
  • Ensure that the client_id provided in the request URL is valid and associated with your account.
  • Only contacts associated with the client_id of the client will be returned.

Was this page helpful?