GorillaDesk

GorillaDesk Customers API

List, create, retrieve, and update customer records - including contacts, phone numbers, and service locations. Endpoints - GET/POST /customers and GET/PUT /customers/{customerId}. This is the core CRM surface of the public v1 API.

GitHub OpenAPI

Documentation

📖
Documentation
https://api.gorilladesk.com/
📖
APIReference
https://api.gorilladesk.com/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/gorilladesk/refs/heads/main/openapi/gorilladesk-openapi.yml

Other Resources

🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/gorilladesk/refs/heads/main/collections/gorilladesk.postman_collection.json
🔗
OpenCollection
https://raw.githubusercontent.com/api-evangelist/gorilladesk/refs/heads/main/collections/gorilladesk.opencollection.json
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/gorilladesk/refs/heads/main/apis.yml

OpenAPI Specification

gorilladesk-openapi.yml Raw ↑ 
openapi: 3.0.3
info:
  title: GorillaDesk API
  description: |
    # Introduction
    The GorillaDesk API is organized around REST.

    Our API has predictable resource-oriented URLs, accepts JSON-encoded and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs..

    # Authentication

    The GorillaDesk API uses Token authentication. API keys are per-company and can be generated and deleted in the [Addons page](https://beta.gorilladesk.com/addons/api).

    # Rate Limits

    We enforce API call rate limits to protect our infrastructure from excessive request rates, to keep GorillaDesk fast and stable for everyone. These limits are high enough that typical API workflows aren't affected. However, please do code your integration to follow the rule below:

    **If you receive a response status code of 429 (Too Many Requests), please sleep/pause for the number of seconds specified by the rate_reset value before making additional requests to that endpoint.**


    Rate limits are enforced per endpoint group. Endpoint groups are used to provide more granular control by grouping endpoint URL paths and methods (e.g. GET, PUT, etc.) together. For instance, GETs to /v1/users/ and POSTs/PUTs to /v1/customers/ may be counted as two different API groups. This allows us to offer a higher limit on lightweight requests than we would be able to on more resource intensive request types.

    API responses will have the following headers to provide rate limiting statistics about the limit it's closest to hitting.

    - `x-rate-limit-limit`: Request limit enforced for this endpoint, some endpoints may allow bursting over this limit
    - `x-rate-limit-remaining`: Requests left in the enforcement window
    - `x-rate-limit-reset`: Seconds remaining before this enforcement window ends (as a decimal).
  x-logo:
    url: 'https://cdn.gorilladesk.com/assets/images/gorilladesk.png'
    altText: GorillaDesk logo
servers:
  - url: 'https://api.gorilladesk.com/v1'
security:
  - Bearer: []
components:
  schemas:
    Company:
      type: object
      properties:
        name:
          type: string
          example: Pest Control
        email:
          type: string
          example: pestcontrol@gmail.com
        phone:
          type: string
          example: (+1)202-555-0156
        website:
          type: string
          example: pestcontrol.com
        address:
          type: string
          example: 12 Norman Stretton Road
        city:
          type: string
          example: Deridder
        state:
          type: string
          example: LA
        zip:
          type: string
          example: '30634'
        timezone:
          type: string
          example: America/Los_Angeles
        office_hours:
          type: object
          properties:
            start:
              type: string
              example: '07:00:00'
            end:
              type: string
              example: '18:00:00'
    User:
      type: object
      properties:
        id:
          type: string
          example: 0nk8PGvAO
        username:
          type: string
          example: johndoe
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        role:
          type: string
          enum:
            - super_admin
            - admin
            - technician
          example: super_admin
        license:
          type: string
          example: '#91161'
        email:
          type: string
          example: example@gmail.com
        avatar:
          type: string
          example: 'https://d2e627ktfmb6xb.cloudfront.net/avatars/static/avatar_1.jpg'
    Customer:
      type: object
      properties:
        id:
          type: string
          description: The customer Id
          example: 0nk8PGvAO
        account_number:
          type: string
          description: Must end with a number
          example: '5047'
        last_name:
          type: string
          example: Doe
        first_name:
          type: string
          example: John
        profile_url:
          type: string
          example: 'https://v3.gorilladesk.com/customers/5393'
        email:
          type: string
          example: example@gmail.com
        phones:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CustomerPhone'
        company:
          type: string
          example: NL software
        source:
          nullable: true
          type: object
          description: Where the customer originated. Null if no source is assigned.
          properties:
            id:
              type: string
              description: Source id.
              example: aWGl2VlY78
            name:
              type: string
              example: Facebook
        tags:
          type: array
          description: Customer-level tag labels attached to this customer.
          items:
            type: string
          example:
            - super
            - vip
        state:
          type: string
          enum:
            - active
            - deleted
          example: active
        status:
          type: string
          enum:
            - active
            - inactive
            - lead
          example: active
        created:
          type: string
          format: date-time
          example: '2023-05-21T17:32:28+00:00'
          description: Created date in ISO format
        updated:
          type: string
          format: date-time
          description: Updated date in ISO format
          example: '2023-05-21T17:32:28+00:00'
        locations:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Location'
        contacts:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/Contact'
    CustomerPhone:
      type: object
      required:
        - phone
        - type
      properties:
        id:
          type: string
          description: Phone Id
          example: 0nk8PGvAO
        phone:
          type: string
          example: 212-456-7890
          description: Phone number
        type:
          type: string
          description: Phone type Id
          example: 0nk8PGvAO
    Location:
      type: object
      required:
        - address_line_1
        - city
        - state
        - zip
      properties:
        id:
          type: string
          example: 5aXrGzNyLY
          readOnly: true
        name:
          type: string
          example: Home
        address_to:
          type: string
          example: John Doe
        address_line_1:
          type: string
          example: 523 East 72nd Street
        address_line_2:
          type: string
          example: ''
        city:
          type: string
          example: New York
        state:
          type: string
          example: NY
        zip:
          type: string
          example: '10021'
        county:
          type: string
          example: ''
        billing_to:
          type: string
          example: John Doe
        billing_address_line_1:
          type: string
          example: 523 East 72nd Street
        billing_address_line_2:
          type: string
          example: ''
        billing_city:
          type: string
          example: New York
        billing_state:
          type: string
          example: NY
        billing_zip:
          type: string
          example: '10021'
        latitude:
          type: string
          example: ''
        longitude:
          type: string
          example: ''
        note:
          type: string
          example: 'Lorem ipsum dolor sit amet, consectetuer adipiscing eliti'
    Contact:
      type: object
      properties:
        id:
          type: string
          example: 5aXrGzNyLY
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        email:
          type: string
          example: example@gmail.com
        phones:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CustomerPhone'
    PhoneType:
      type: object
      properties:
        id:
          type: string
          example: 0nk8PGvAO
        name:
          type: string
          example: Mobile
        is_default:
          type: boolean
          example: true
        state:
          type: string
          enum:
            - active
            - deleted
          example: active
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
paths:
  /company:
    get:
      summary: Retrieve company
      tags:
        - Company
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/paths/~1users/get/responses/401'
  /users:
    get:
      summary: List all users
      tags:
        - User
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  has_more:
                    type: boolean
        '401':
          description: Unauthorized error
        '403':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - message
                properties:
                  error:
                    type: object
                    nullable: true
                  message:
                    type: string
  '/users/{userId}':
    get:
      summary: Retrieve a user
      tags:
        - User
      parameters:
        - in: path
          name: userId
          description: User Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '404':
          description: Not Found
  /customers:
    get:
      summary: List all customers
      tags:
        - Customer
      parameters:
        - in: query
          name: state
          schema:
            type: array
            items:
              type: string
              enum:
                - active
                - deleted
          example: 'active,deleted'
        - in: query
          name: status
          schema:
            type: array
            items:
              type: string
              enum:
                - active
                - inactive
                - lead
          example: 'active,inactive,lead'
        - in: query
          name: account_number
          description: Return results where the account_number field is equal this value.
          schema:
            type: string
          example: '5000'
        - in: query
          name: 'created[gt]'
          description: Return results where the created field is greater than this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'created[gte]'
          description: Return results where the created field is greater than or equal this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'created[lt]'
          description: Return results where the created field is less than this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'created[lte]'
          description: Return results where the created field is less than or equal this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'updated[gt]'
          description: Return results where the updated field is greater than this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'updated[gte]'
          description: Return results where the updated field is greater than or equal this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'updated[lt]'
          description: Return results where the updated field is less than this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: 'updated[lte]'
          description: Return results where the updated field is less than or equal this value.
          schema:
            type: string
            format: date-time
          example: '2023-05-21T17:32:28+00:00'
        - in: query
          name: include
          schema:
            type: array
            items:
              type: string
              enum:
                - locations
                - contacts
          example: 'locations,contacts'
        - in: query
          name: sort
          description: 'Prefix -[field] sort order is descending.'
          schema:
            type: array
            items:
              type: string
              enum:
                - account_number
                - last_name
                - first_name
                - created
                - updated
          example: 'account_number,last_name,-created'
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  has_more:
                    type: boolean
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '403':
          $ref: '#/paths/~1users/get/responses/403'
    post:
      summary: Create a customer
      tags:
        - Customer
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/paths/~1customers~1%7BcustomerId%7D/put/requestBody/content/application~1json/schema'
                - type: object
                  properties:
                    location:
                      $ref: '#/components/schemas/Location'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '403':
          $ref: '#/paths/~1users/get/responses/403'
  '/customers/{customerId}':
    get:
      summary: Retrieve a customer
      tags:
        - Customer
      parameters:
        - in: path
          name: customerId
          description: Customer Id
          required: true
          schema:
            type: string
        - in: query
          name: include
          schema:
            type: array
            items:
              type: string
              enum:
                - locations
                - contacts
          example: 'locations,contacts'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '403':
          $ref: '#/paths/~1users/get/responses/403'
        '404':
          $ref: '#/paths/~1users~1%7BuserId%7D/get/responses/404'
    put:
      summary: Update a customer
      tags:
        - Customer
      parameters:
        - in: path
          name: customerId
          description: Customer Id
          required: true
          schema:
            type: string
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - location
              properties:
                account_number:
                  type: string
                  description: Must end with a number
                  example: '5047'
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                status:
                  type: string
                  enum:
                    - active
                    - inactive
                    - lead
                  example: active
                email:
                  type: string
                  example: example@gmail.com
                phones:
                  type: array
                  items:
                    type: object
                    $ref: '#/components/schemas/CustomerPhone'
                company:
                  type: string
                  example: NL software
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '403':
          $ref: '#/paths/~1users/get/responses/403'
        '404':
          $ref: '#/paths/~1users~1%7BuserId%7D/get/responses/404'
  /phone-types:
    get:
      summary: List all phone types
      tags:
        - Phone Type
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneType'
                  has_more:
                    type: boolean
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '403':
          $ref: '#/paths/~1users/get/responses/403'
  '/customers/{customerId}/notes':
    post:
      summary: Create a customer note
      tags:
        - Note
      parameters:
        - in: path
          name: customerId
          description: Customer Id
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  example: 'Lorem, ipsum dolor sit amet consectetur adipisicing elit'
                notify_users:
                  type: array
                  description: List of user Ids
                  items:
                    type: string
                    example: jVepBjQp0E
                attachments:
                  type: array
                  description: |
                    Files to upload.
                    Accepted file types: image, audio, video, pdf.
                    Limit to 5 files and maximum 10MB per file.
                  items:
                    type: string
                    format: binary
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 5aXrGzNyLY
        '401':
          $ref: '#/paths/~1users/get/responses/401'
        '403':
          $ref: '#/paths/~1users/get/responses/403'
        '404':
          $ref: '#/paths/~1users~1%7BuserId%7D/get/responses/404'