AppZen Entities API

swagger: '2.0'
info:
  title: Autonomous AP APIs Chart of Accounts Entities API
  description: Public APIs for integrating with Autonomous AP
  version: 2.0.3
host: <env>.appzen.com
basePath: /dictionary-data-services
schemes:
- https
security:
- API Key Header: []
  Customer Id Header: []
  Customer Key Header: []
tags:
- name: Entities
paths:
  /entity:
    post:
      tags:
      - Entities
      summary: Creates/updates an entity
      description: Creates a new entity in AppZen. Returns a uuid for this entity. When there already exists an entity (with the same uuid), then the operation is an update (in this case, the `status` in the response will be `UPDATED`).
      parameters:
      - $ref: '#/parameters/entity-schema'
      responses:
        200:
          description: Updated
          schema:
            $ref: '#/definitions/uuid-updated'
        201:
          description: Created
          schema:
            $ref: '#/definitions/uuid'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
  /entity/{uuid}:
    get:
      tags:
      - Entities
      summary: Returns entity details
      description: Returns the details of a entity by uuid
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/uuid'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/entity'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
  /entity/external-entity-id/{external-entity-id}:
    get:
      tags:
      - Entities
      summary: Returns entity details
      description: Returns the details of a entity by external entity id
      produces:
      - application/json
      parameters:
      - in: path
        description: external entity id
        required: true
        name: external-entity-id
        type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/entity'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
  /entity/search:
    post:
      tags:
      - Entities
      summary: Returns all Entities uuid that match the search criteria
      description: Returns a list of the Entities uuids that match from-date and end-date
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/find-query-spec'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/find-entity-result-spec'
        400:
          description: Bad Request
          schema:
            $ref: '#/definitions/http-400-error-response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/http-401-error-response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/http-403-error-response'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/http-404-error-response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/http-500-error-response'
definitions:
  http-500-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 500
      error:
        type: string
        example: Internal Server Error
      message:
        type: string
        example: 'Error code : 17e3338d - Unable to process your request at this moment, please try again later'
  http-404-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 404
      error:
        type: string
        example: Not Found
      message:
        type: string
        example: 'Error code : 17e3338d - The resource you specified cannot be not found'
  data-lookup-names:
    type: object
    properties:
      coa_lookup_names:
        type: array
        description: If "" or " " (white space only, no lookup context is specified for the corresponding coa_structure element.
        example:
        - us_lookups
        - ''
        - ' '
        - f1_list
      supplier_lookup_name:
        type: string
        description: associated supplier lookup name list
        example: s1
  http-403-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 403
      error:
        type: string
        example: Forbidden
      message:
        type: string
        example: 'Error code : 17e3338d - You do not have permission to access this resource'
  http-400-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 400
      error:
        type: string
        example: Bad Request
      message:
        type: string
        example: 'Error code : 17e3338d - Invalid request, please fix and resend'
  addressCore:
    required:
    - address_line1
    - country
    - zip
    properties:
      address_line1:
        default: ''
        title: The address_line1 schema
        type: string
        example: 12345 MARKET STREET
      address_line2:
        default: ''
        title: The address_line2 schema
        type: string
        example: SUITE 1234
      address_line3:
        default: ''
        title: The address_line3 schema
        type: string
        example: ''
      area_code:
        default: ''
        title: The area_code schema
        type: string
        example: '415'
      city:
        default: ''
        title: The city schema
        type: string
        example: SAN FRANCISCO
      company:
        default: ''
        title: The company schema
        type: string
        example: Preferred Supplier Inc.
      contact:
        default: ''
        title: The contact schema
        type: string
        example: Jane Doe
      country:
        default: ''
        title: The country schema
        type: string
        example: US
      country_iso3:
        default: ''
        title: The country_iso3 schema
        type: string
        example: USA
      email:
        default: ''
        title: The email schema
        type: string
        example: janedoe@supplier.com
      phone:
        default: ''
        title: The phone schema
        type: string
        example: '4042965282'
      province:
        default: ''
        title: The province schema
        type: string
        example: ''
      state:
        default: ''
        title: The state schema
        type: string
        example: CA
      zip:
        default: ''
        title: The zip schema
        type: string
        example: '94016'
  uuid:
    type: object
    properties:
      uuid:
        type: string
        example: 5fc03087-d265-11e7-b8c6-83e29cd24f4c
      status:
        type: string
        example: CREATED
  find-query-spec:
    description: The date range must be limited to 7 days
    properties:
      from-last-appzen-update-time:
        description: Start Date Range value for Appzen processing date specified in UTC format
        allOf:
        - $ref: '#/definitions/date-time'
      to-last-appzen-update-time:
        description: End Date Range for Appzen processing date specified in UTC format
        allOf:
        - $ref: '#/definitions/date-time'
      limit:
        description: Number of matched records to return
        type: number
        default: 1000
        maximum: 1000
        example: 50
    required:
    - from-last-appzen-update-time
    - to-last-appzen-update-time
  entity-addresses:
    type: array
    items:
      allOf:
      - $ref: '#/definitions/entity-address'
  uuid-updated:
    type: object
    properties:
      uuid:
        type: string
        example: 5fc03087-d265-11e7-b8c6-83e29cd24f4c
      status:
        type: string
        example: UPDATED
  date-time:
    type: string
    format: date-time
    example: '2024-03-01T11:01:00Z'
    description: date should be in UTC format
  find-entity-result-spec:
    example:
    - entity-id: '1951243072'
      appzen-uuid: 506dd9b6-a93c-48fc-98e8-919093032b49
      is-active: false
      last-appzen-update-time: '2021-12-08T23:00:17.724Z'
    - entity-id: '1623599683'
      appzen-uuid: f43c0612-11b5-4965-9554-425fbffdda6d
      is-active: false
      last-appzen-update-time: '2021-12-08T23:30:15.368Z'
    properties:
      entity-id:
        type: string
      appzen-uuid:
        type: string
      is-active:
        type: boolean
      last-appzen-update-time:
        type: string
  http-401-error-response:
    type: object
    properties:
      timestamp:
        type: string
        example: 2019-01-17T16:12:45.977+0000
      status:
        type: string
        example: 401
      error:
        type: string
        example: Unauthorized
      message:
        type: string
        example: 'Error code : 17e3338d - Unable to authenticate credentials'
  entity:
    properties:
      entity_id:
        description: Unique id distinguishing entity from other entity (PK)
        type: string
      entity_name:
        description: Valid entity name present used in the ERP system
        type: string
      parent_entity_id:
        description: Valid parent entity id present in the ERP system
        type: string
      entity_type:
        description: Entity type defined within the customer's ERP system
        type: string
      appzen_entity_type:
        description: Value for appzen to understand this entity. Refer to the entity enum for recognized values.
        example: LEGAL_ENTITY
        enum:
        - LEGAL_ENTITY
        - OTHER_ENTITY
        - COMPANY
        type: string
      entity_alias_name:
        default: ''
        description: All the alias names that refers to this entity
        type: array
      addresses:
        allOf:
        - $ref: '#/definitions/entity-addresses'
      currency:
        description: Default currency associated to this entity
        type: string
      coa_structure:
        description: This is case sensitive list of coa structure. It should be in the same sequence as gl-code in the ERP system.
        example:
        - Entity
        - Department
        - Line of Business
        - Future1
        type: array
      appzen_coa_structure:
        description: Refers to the AppZen mapped values. Please provide the mapped values in the same sequence as the customer coa_structure. OTHER_SEGMENT should be used to map any customer segment type that does not have correspondence with one of the named appzen segment types (e.g. ACCOUNT_SEGMENT, DEPARTMENT_SEGMENT etc). Multiple OTHER_SEGMENT mappings may be specified, if needed.
        example:
        - LEGAL_ENTITY_SEGMENT
        - DEPARTMENT_SEGMENT
        - OTHER_SEGMENT
        - OTHER_SEGMENT
        type: array
      dataset_lookup_names:
        description: one to one mapping with coa_structure fields to specify optional lookup contexts.
        allOf:
        - $ref: '#/definitions/data-lookup-names'
      optional_segments:
        description: This is case sensitive list of items from coa_structure that are optional.
        example:
        - Department
        - Future1
        type: array
      is_active:
        description: If entity is active in the ERP system
        default: true
        type: boolean
      valid_start_date:
        allOf:
        - $ref: '#/definitions/date-time'
      valid_end_date:
        allOf:
        - $ref: '#/definitions/date-time'
      created_date:
        allOf:
        - $ref: '#/definitions/date-time'
      updated_date:
        allOf:
        - $ref: '#/definitions/date-time'
      payment_term_id:
        description: Payment term id associated with this entity
        type: string
      custom_json:
        type: object
        example:
          bu_id: 382
          bu_name: HR
    required:
    - entity_id
    - entity_name
    - entity_type
    - appzen_entity_type
    - currency
    - addresses
  entity-address:
    type: object
    required:
    - address_type
    properties:
      address_type:
        type: string
        enum:
        - REMIT_TO
        - BILL_TO
        - SHIP_TO
        - OFFICE
        - SUPPLIER_ADDRESS
        - CUSTOMER_ADDRESS
        - NONE_ADDRESS_TYPE
      address:
        allOf:
        - $ref: '#/definitions/addressCore'
      site_id:
        type: string
        example: '913838'
      site_name:
        type: string
        example: California HQ
      custom_json:
        type: object
        properties:
          key1:
            type: string
            example: value1
parameters:
  uuid:
    in: path
    description: Globally unique identifier for an uploaded document
    required: true
    name: uuid
    type: string
  find-query-spec:
    in: body
    description: Query Criterion for locating Items
    required: true
    name: find-query-spec
    schema:
      $ref: '#/definitions/find-query-spec'
  entity-schema:
    in: body
    required: true
    name: entity-schema
    schema:
      $ref: '#/definitions/entity'
securityDefinitions:
  API Key Header:
    type: apiKey
    in: header
    name: x-api-key
  Customer Id Header:
    type: apiKey
    in: header
    name: customer-id
  Customer Key Header:
    type: apiKey
    in: header
    name: customer-key