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

# Creates a contact under a client, or a temporary contact when no client is given.

> With a ClientId the contact belongs to that client. Without one it is created as a temporary
contact (IsTemporaryContact true) with no client and no location - the kind of contact an
email from an unknown requester creates - and it can be used as the contact or a cc contact
on a ticket that has no client. A LocationId needs a ClientId.
            
If another contact, active or temporary, already has the primary email address, nothing is
created and the response is a 409 whose message carries that contact's id: use it rather
than retrying. This endpoint never updates an existing contact.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/contacts
openapi: 3.0.4
info:
  title: Public API
  description: Gorelo Public API documentation.
  version: 1.0.0
servers:
  - url: https://api.usw.gorelo.io
    description: US
  - url: https://api.aue.gorelo.io
    description: Australia
security:
  - ApiKeyAuth: []
tags:
  - name: Attachments
    description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs."
  - name: Alerts
    description: Alerts management operations
  - name: Assets
    description: Assets management operations
  - name: Billing
    description: Billing management operations
  - name: Tickets
    description: Tickets management operations
  - name: Clients
    description: Clients management operations
  - name: Contacts
    description: Contacts management operations
  - name: Deletions
    description: Deletions management operations
  - name: Documents
    description: Documents management operations
  - name: Forms
    description: Forms management operations
  - name: Organization
    description: Organization management operations
  - name: Projects
    description: Projects management operations
paths:
  /v1/contacts:
    post:
      tags:
        - Contacts
      summary: >-
        Creates a contact under a client, or a temporary contact when no client
        is given.
      description: "With a ClientId the contact belongs to that client. Without one it is created as a temporary\r\ncontact (IsTemporaryContact true) with no client and no location - the kind of contact an\r\nemail from an unknown requester creates - and it can be used as the contact or a cc contact\r\non a ticket that has no client. A LocationId needs a ClientId.\r\n            \r\nIf another contact, active or temporary, already has the primary email address, nothing is\r\ncreated and the response is a 409 whose message carries that contact's id: use it rather\r\nthan retrying. This endpoint never updates an existing contact."
      operationId: post_v1_contacts
      requestBody:
        description: Contact details.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateContactCommand'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactCommand'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateContactCommand'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateContactCommand'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ContactResponseBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponseBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ContactResponseBaseResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '409':
          description: Conflict
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
components:
  schemas:
    CreateContactCommand:
      required:
        - FirstName
        - LastName
        - PrimaryEmail
      type: object
      properties:
        FirstName:
          minLength: 1
          type: string
          description: Contact first name. Required. Maximum 150 characters.
          example: Jane
        LastName:
          minLength: 1
          type: string
          description: Contact last name. Required. Maximum 150 characters.
          example: Doe
        ClientId:
          type: integer
          description: "Identifier of the client the contact belongs to. Optional. When omitted the contact is\r\ncreated as a temporary contact (IsTemporaryContact true) with no client, the way an email\r\nfrom an unknown requester creates one; a temporary contact can be the contact or a cc\r\ncontact on a ticket that has no client."
          format: int64
          nullable: true
        LocationId:
          type: integer
          description: >-
            Identifier of the client location the contact belongs to. Requires
            ClientId.
          format: int64
          nullable: true
        PrimaryEmail:
          minLength: 1
          type: string
          description: Primary email address. Required. Maximum 200 characters.
          example: jane.doe@contoso.com
        SecondaryEmail:
          type: array
          items:
            type: string
          description: Additional (secondary) email addresses. Maximum 200 characters each.
          nullable: true
        MobilePhone:
          type: string
          description: >-
            Mobile phone number, as dialled within its country, e.g. 021 123
            4567 for NZ; an international +64 21 123 4567 is accepted too. A
            number sent without its leading 0 (21 123 4567) is stored with it.
            Maximum 20 characters.
        MobilePhoneCountryCode:
          type: string
          description: >-
            Mobile phone ISO 3166-1 alpha-2 region code (e.g. US). Maximum 100
            characters.
        OfficePhone:
          type: string
          description: >-
            Office phone number, as dialled within its country, e.g. 021 123
            4567 for NZ; an international +64 21 123 4567 is accepted too. A
            number sent without its leading 0 (21 123 4567) is stored with it.
            Maximum 20 characters.
        OfficePhoneCountryCode:
          type: string
          description: >-
            Office phone ISO 3166-1 alpha-2 region code (e.g. US). Maximum 25
            characters.
        JobTitle:
          type: string
          description: Contact job title. Maximum 100 characters.
        Department:
          type: string
          description: Contact department. Maximum 150 characters.
        TimeZone:
          type: string
          description: >-
            IANA time zone identifier for the contact (e.g. America/New_York).
            Maximum 50 characters.
        Description:
          type: string
          description: >-
            Free-text description / notes for the contact. Maximum 2000
            characters.
      additionalProperties: false
      description: >-
        Request body for creating a contact, under a client or, with no client,
        as a temporary contact.
    ContactResponseBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          $ref: '#/components/schemas/ContactResponse'
        DataContext:
          type: object
          additionalProperties: false
          nullable: true
          example: null
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    ObjectBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          nullable: true
        DataContext:
          $ref: '#/components/schemas/ErrorDataContext'
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    HttpStatusCode:
      enum:
        - 100
        - 101
        - 102
        - 103
        - 200
        - 201
        - 202
        - 203
        - 204
        - 205
        - 206
        - 207
        - 208
        - 226
        - 300
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
        - 308
        - 400
        - 401
        - 402
        - 403
        - 404
        - 405
        - 406
        - 407
        - 408
        - 409
        - 410
        - 411
        - 412
        - 413
        - 414
        - 415
        - 416
        - 417
        - 421
        - 422
        - 423
        - 424
        - 426
        - 428
        - 429
        - 431
        - 451
        - 500
        - 501
        - 502
        - 503
        - 504
        - 505
        - 506
        - 507
        - 508
        - 510
        - 511
      type: integer
      format: int32
    ContactResponse:
      type: object
      properties:
        Id:
          type: integer
          description: Contact identifier.
          format: int64
        FirstName:
          type: string
          description: Contact first name.
        LastName:
          type: string
          description: Contact last name.
        Status:
          $ref: '#/components/schemas/CodeModel'
        ClientId:
          type: integer
          description: Identifier of the client the contact belongs to.
          format: int64
          nullable: true
        LocationId:
          type: integer
          description: Identifier of the client location the contact belongs to.
          format: int64
          nullable: true
        CreatedOn:
          type: string
          description: Creation timestamp (UTC).
          format: date-time
          nullable: true
        UpdatedOn:
          type: string
          description: Last-updated timestamp (UTC).
          format: date-time
          nullable: true
        PrimaryEmail:
          type: string
          description: Primary email address.
        Alias:
          type: string
          description: Contact alias.
        MobilePhone:
          type: string
          description: >-
            Mobile phone number, as dialled within its country, e.g. 021 123
            4567 for NZ.
        MobilePhoneCountryCode:
          type: string
          description: Mobile phone ISO 3166-1 alpha-2 region code (e.g. US).
        OfficePhone:
          type: string
          description: >-
            Office phone number, as dialled within its country, e.g. 021 123
            4567 for NZ.
        OfficePhoneCountryCode:
          type: string
          description: Office phone ISO 3166-1 alpha-2 region code (e.g. US).
        JobTitle:
          type: string
          description: Contact job title.
        Department:
          type: string
          description: Contact department.
        TimeZone:
          type: string
          description: IANA time zone identifier for the contact.
        Description:
          type: string
          description: Free-text description / notes.
        IsTemporaryContact:
          type: boolean
          description: Whether the contact is a temporary (auto-created) contact.
        MergedWithContactId:
          type: integer
          description: Identifier of the contact this one was merged with, if any.
          format: int64
          nullable: true
      additionalProperties: false
      description: A contact belonging to a client. Timestamps are UTC.
    Error:
      type: object
      properties:
        Code:
          pattern: ^[0-9]{6}$
          type: string
          description: 6-digit MMTTNN error code. See the Public API error-code registry.
          example: '070101'
        Message:
          type: string
        PropertyName:
          type: string
          nullable: true
        ActionHint:
          type: string
          nullable: true
        DocUrl:
          type: string
          nullable: true
      additionalProperties: false
    ErrorDataContext:
      type: object
      properties:
        TraceId:
          type: string
          description: Request correlation id. Quote this when reporting a problem.
          nullable: true
      additionalProperties: false
      description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest."
    CodeModel:
      type: object
      properties:
        Id:
          type: integer
          description: >-
            Numeric identifier of the coded value (e.g. status, priority, type,
            or source id).
          format: int64
          example: 1
        Name:
          type: string
          description: Display name of the coded value.
      additionalProperties: false
      description: >-
        A coded value, such as a status, priority, type or source, as an id and
        a display name.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        Your Gorelo API key. See [Generate API key](/generate-api-key). If your
        data is hosted in Australia, click the base URL at the top of this page
        and select `https://api.aue.gorelo.io`.
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.