openapi: 3.2.0
info:
  title: Vibes Platform Person API
  version: 1.0.0
servers:
- url: https://public-api.vibescm.com
  description: North America
- url: https://public-api.eu.vibes.com/
  description: EMEA
security:
- basicAuth: []
tags:
- name: Person API
paths:
  /companies/{company_key}/mobiledb/persons/{person_key}:
    get:
      tags:
      - Person API
      summary: Get person by person_key
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: person_key
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personResponse'
        '404':
          description: The person record cannot be found using this `person_key`.
        '422':
          description: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
    put:
      tags:
      - Person API
      summary: Update person by person_key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personRequest'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
        required: true
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: person_key
        in: path
        schema:
          type: string
        required: true
        description: <div style="color:#dd1e2e; background:url(https://d2xs7zaan7w9gl.cloudfront.net/data/pages/64014/widgets/48027d01-e827-45e0-b96d-227c1099eedc/image/1680214872.png?icon-24x24-warning.png) no-repeat 10px center; background-color:#FCEAEC; padding:10px; font-size:13px;"><div style="padding-left:35px"><b>Important:</b> If you are entering a real person_key, please note that using the <b>"Try It"</b> feature on the righthand console will send an actual API call to our system. This may result in a person record being updated.</div></div>
      responses:
        '200':
          description: Successful response. An existing person record was identified and the specified fields have been updated. Any existing data fields on the record will remain unchanged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personResponse'
        '201':
          description: Person record has been updated.
        '409':
          description: Conflict error. This may occur if you are attempting to update an MDN. Note that you cannot update an MDN on an existing person record, but you may remove an MDN by setting the value to `null`.
        '422':
          description: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
  /companies/{company_key}/mobiledb/persons/external/{external_person_id}:
    get:
      tags:
      - Person API
      summary: Get person by external_person_id
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: external_person_id
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personResponse'
        '404':
          description: Person record cannot be found using the specified `external_person_id`.
        '422':
          description: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
    put:
      tags:
      - Person API
      summary: Update person by external_person_id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personRequest'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
        required: true
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: external_person_id
        in: path
        schema:
          type: string
        required: true
        description: <div style="color:#dd1e2e; background:url(https://d2xs7zaan7w9gl.cloudfront.net/data/pages/64014/widgets/48027d01-e827-45e0-b96d-227c1099eedc/image/1680214872.png?icon-24x24-warning.png) no-repeat 10px center; background-color:#FCEAEC; padding:10px; font-size:13px;"><div style="padding-left:35px"><b>Important:</b> If you are entering a real external_person_id, please note that using the <b>"Try It"</b> feature on the righthand console will send an actual API call to our system. This may result in a person record being updated.</div></div>
      responses:
        '200':
          description: Successful response. An existing person record already exists, and the record will be updated with the added information. Any existing data fields on the record will remain unchanged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personResponse'
        '201':
          description: Person record has been successfully updated.
        '409':
          description: Conflict error. This occurs if you are attempting to update an MDN. An MDN cannot be updated, but it can be removed if you set its value to `null`.
        '422':
          description: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
  /companies/{company_key}/mobiledb/persons:
    get:
      tags:
      - Person API
      summary: Find person by MDN
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: company_key
        in: path
        schema:
          type: string
        required: true
      - name: mdn
        in: query
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personResponse'
        '400':
          description: Invalid MDN format. If you are using E.164 format, be sure to include %2B in place of +.
        '404':
          description: MDN not found. This can be returned if you don’t specify an MDN, or if there are no person records associated with that MDN.
  /companies/{company_key}/mobiledb/persons/:
    post:
      tags:
      - Person API
      summary: Add a person
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personRequest'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 1
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
        required: true
      - name: company_key
        in: path
        schema:
          type: string
        required: true
        description: <div style="color:#dd1e2e; background:url(https://d2xs7zaan7w9gl.cloudfront.net/data/pages/64014/widgets/48027d01-e827-45e0-b96d-227c1099eedc/image/1680214872.png?icon-24x24-warning.png) no-repeat 10px center; background-color:#FCEAEC; padding:10px; font-size:13px;"><div style="padding-left:35px"><b>Important:</b> Please note that the <b>"Try It"</b> feature to the right will send an actual API call to our system, which may result in a new person record being created.</div></div>
      responses:
        '200':
          description: Successful response. An existing person record already exists with the same MDN. The record will be updated with the added information, and any unspecified data fields on the record will remain unchanged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/personResponse'
        '201':
          description: A person record has been created.
        '409':
          description: Conflict error. Generally, this occurs if you are attempting to create a person record with an MDN that is already associted with another person record.
        '422':
          description: The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
components:
  schemas:
    personResponse:
      type: object
      properties:
        person_key:
          type: string
          description: A unique Vibes-asigned alphanumeric identifier for each person record.
        external_person_id:
          type: string
          description: A unique person identifier assigned by the brand, which can be used to link non-Vibes-assigned identifiers to Vibes person records. Max 128 characters.
        mobile_phone:
          type: object
          description: Object representation of a person's mobile phone. A person can have only one active mobile phone at a time.
          properties:
            mdn:
              type: string
              description: Mobile Directory Number. The dialable phone number associated with the phone.
            carrier_code:
              type: string
              description: The cellular carrier associated with this mobile number.
        custom_fields:
          type: object
          description: list of custom field key/value pairs.
          additionalProperties:
            type: string
        created_at:
          type: string
          description: The date this person was created, in the ISO-8601 format.
        updated_at:
          type: string
          description: The date this person was last updated, in the ISO-8601 format.
        url:
          type: string
    personRequest:
      type: object
      properties:
        external_person_id:
          type: string
          description: A unique person identifier assigned by the brand, which can be used to link non-Vibes-assigned identifiers to Vibes person records. Max 128 characters.
        mobile_phone:
          type: object
          description: Object representation of a person's mobile phone. A person can have only one active mobile phone at a time.
          properties:
            mdn:
              type: string
              description: Mobile Directory Number. The dialable phone number associated with the phone.
            carrier_code:
              type: string
              description: The cellular carrier associated with this mobile number.
        custom_fields:
          type: object
          description: List of custom field key/value pairs.
          additionalProperties:
            type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic