openapi: 3.0.3

info:
  title: Participants
  description: "For retrieving Participants. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

externalDocs:
  description: API Developer Portal - Constructing API Requests
  url: https://docs.actionstep.com/api-requests/

paths:
  '/participants':
    get:
      description: Returns a collection of participants. For information on how to construct requests filtering by various properties, please refer to the API Developer Portal.
      tags:
        - Participants
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedParticipants'

    post:
      description: Create a new participant.
      tags:
        - Participants
      requestBody:
        $ref: '#/components/requestBodies/CreateParticipant'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'

  '/participants/{id}':
    get:
      description: Returns a single participant.
      tags:
        - Participants
      parameters:
        - name: id
          in: path
          description: Unique identifier for a Participant.
          required: true
          schema:
            type: integer
          example: 7630
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'

    put:
      description: Updates a participant
      tags:
        - Participants
      requestBody:
        $ref: '#/components/requestBodies/UpdateParticipant'
      parameters:
        - name: id
          in: path
          description: Unique identifier for a participant.
          required: true
          schema:
            type: integer
          example: 7630
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'

components:
  schemas:
    PagedParticipants:
      type: object
      properties:
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        participants:
          $ref: '#/components/schemas/ParticipantsPageData'

    ParticipantsPageData:
      type: object
      properties:
        recordCount:
          description: The total number of participants returned by the underlying query.
          type: integer
          example: 2317
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 47
        page:
          description: The page number for this page of participants.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of participants.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/participants?page=1
        nextPage:
          description: A URL to the next page of participants.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/participants?page=3

    Participant:
      type: object
      properties:
        id:
          description: Unique identifier for the participant.
          example: 7939
          type: integer
        displayName:
          description: Display name for the participant. This is typically the first name and last name displayed in the order specified by your system's settings.
          example: Bond, James
          type: string
        isCompany:
          description: Indicates if the participant is an individual or a company/organisation.
          example: F
          type: string
        companyName:
          description: Company or organisation name.
          example: Actionstep
          type: string
        salutation:
          description: Salutation.
          example: Mrs
          type: string
        firstName:
          description: First name.
          example: James
          type: string
        middleName:
          description: Middle name.
          example: Edward
          type: string
        lastName:
          description: Last name.
          example: Bond
          type: string
        suffix:
          description: Name suffix.
          example: Jnr
          type: string
        preferredName:
          description: Preferred name.
          example: 007
          type: string
        physicalAddressLine1:
          description: First line of the physical address.
          example: MI5 House
          type: string
        physicalAddressLine2:
          description: Second line of the physical address.
          example: South Bank
          type: string
        physicalCity:
          description: City for the physical address.
          example: London
          type: string
        physicalStateProvince:
          description: State or province for the physical address.
          example: Florida
          type: string
        physicalCounty:
          description: County for the physical address.
          example: Dorset
          type: string
        physicalPostCode:
          description: Postcode or zip code for the physical address.
          example: EC2 3YP
          type: string
        mailingAddressLine1:
          description: First line of the mailing address.
          example: 15 Wiltshire Avenue
          type: string
        mailingAddressLine2:
          description: Second line of the mailing address.
          example: South Park
          type: string
        mailingCity:
          description: City for the mailing address.
          example: Poole
          type: string
        mailingStateProvince:
          description: State or province for the mailing address.
          example: New York
          type: string
        mailingCounty:
          description: County for the mailing address.
          example: Hampshire
          type: string
        mailingPostCode:
          description: Postcode or zip code for the mailing address.
          example: BH18 8EJ
          type: string
        phone1Label:
          description: Label for the first telephone number.
          example: Home
          type: string
        phone1Country:
          description: ISO country code for the first telephone number.
          example: 44
          type: integer
        phone1Area:
          description: Area number for the first telephone number.
          example: 202
          type: integer
        phone1Number:
          description: Local part of the first telephone number.
          example: 7379 939
          type: string
        phone1Notes:
          description: Optional notes for the first telephone number.
          example: null
          type: string
        phone2Label:
          description: Label for the second telephone number.
          example: Office
          type: string
        phone2Country:
          description: ISO country code for the second telephone number.
          example: 44
          type: integer
        phone2Area:
          description: Area number for the second telephone number.
          example: 202
          type: integer
        phone2Number:
          description: Local part of the second telephone number.
          example: 6893 378
          type: string
        phone2Notes:
          description: Optional notes for the second telephone number.
          example: null
          type: string
        phone3Label:
          description: Label for the third telephone number.
          example: Mobile
          type: string
        phone3Country:
          description: ISO country code for the third telephone number.
          example: 44
          type: integer
        phone3Area:
          description: Area number for the third telephone number.
          example: 204
          type: integer
        phone3Number:
          description: Local part of the third telephone number.
          example: 0279 6394
          type: string
        phone3Notes:
          description: Optional notes for the third telephone number.
          example: null
          type: string
        phone4Label:
          description: Label for the fourth telephone number.
          example: Holiday home
          type: string
        phone4Country:
          description: ISO country code for the fourth telephone number.
          example: 44
          type: integer
        phone4Area:
          description: Area number for the fourth telephone number.
          example: 393
          type: integer
        phone4Number:
          description: Local part of the fourth telephone number.
          example: 0921 832
          type: string
        phone4Notes:
          description: Optional notes for the fourth telephone number.
          example: Only during summer months.
          type: string
        fax:
          description: Fax number.
          example: 202 3782 838
          type: string
        sms:
          description: Number for SMS messaging.
          example: 93 382 2223
          type: string
        email:
          description: Email address.
          example: james.bond@mi5.co.uk
          type: string
        website:
          description: Website address (Url).
          example: www.myorganisation.com
          type: string
        occupation:
          description: Occupation.
          example: Dentist
          type: string
        taxNumber:
          description: Tax number.
          example: NH838-23M
          type: string
        birthTimestamp:
          description: Date of birth.
          example: 23-May-1987
          type: string
          format: date
        deathTimestamp:
          description: Date of death.
          example: 09-Dec-2020
          type: string
          format: date
        maritalStatus:
          description: Marital status.
          example: Married
          type: string
        gender:
          description: Gender.
          enum:
            - M
            - F
          example: M
          type: string
        genderTypeName:
          description: Gender type name.
          example: Transgender
          type: string
        isDeceased:
          description: Indicates if dead.
          enum:
            - T
            - F
          example: F
          type: string
        dateOfBirthStatus:
          description: Status for date of birth.
          enum:
            - Known
            - Estimate
            - Not stated
            - Unknown
          default: Known
          example: Known
          type: string
        countryIdOfBirth:
          description: 2 character ISO country code.
          example: NZ
          type: string
        modifiedTimestamp:
          description: Date and time of last modification.
          example: 2023-11-08T17:17:29+13:00
          type: string
          format: timestamp
        createdTimestamp:
          description: Date and time of record creation.
          example: 2019-11-05T14:23:48+13:00
          type: string
          format: timestamp
        amlStatus:
          description: Current AML status.
          enum:
            - Not started
            - In progress
            - Signed off
          default: Not started
          example: In progress
          type: string
        amlProgress:
          description: Progress of the AML process expressed as a percentage.
          example: 75
          type: integer
          default: 0
        amlRisk:
          description: AML risk profile.
          enum:
            - Low
            - Medium
            - High
            - Unknown
          default: Unknown
          example: Medium
          type: string
        amlNote:
          description: AML notes.
          example: Successfully processed.
          type: string
        importExternalReference:
          description: Used when importing data into Actionstep from a third-party data source.
          example: DDH-3838939-333
          type: string
        links:
          $ref: '#/components/schemas/ParticipantLinks'

    ParticipantLinks:
      type: object
      properties:
        physicalCountry:
          description: The 2 character ISO code for the country.
          example: NZ
          type: string
        mailingCountry:
          description: The 2 character ISO code for the mailing country.
          example: NZ
          type: string
        division:
          description: Unique identifier of the division to which the participant is associated.
          example: 1
          type: integer

    CreateParticipant:
      type: object
      required:
        - displayName
      properties:
        displayName:
          description: Display name for the participant. This is typically the first name and last name displayed in the order specified by your system's settings.
          example: Bond, James
          type: string
        isCompany:
          description: Indicates if the participant is an individual or a company/organisation.
          example: F
          type: string
        companyName:
          description: Company or organisation name.
          example: Actionstep
          type: string
        salutation:
          description: Salutation.
          example: Mrs
          type: string
        firstName:
          description: First name.
          example: James
          type: string
        middleName:
          description: Middle name.
          example: Edward
          type: string
        lastName:
          description: Last name.
          example: Bond
          type: string
        suffix:
          description: Name suffix.
          example: Jnr
          type: string
        preferredName:
          description: Preferred name.
          example: 007
          type: string
        physicalAddressLine1:
          description: First line of the physical address.
          example: MI5 House
          type: string
        physicalAddressLine2:
          description: Second line of the physical address.
          example: South Bank
          type: string
        physicalCity:
          description: City for the physical address.
          example: London
          type: string
        physicalStateProvince:
          description: State or province for the physical address.
          example: Florida
          type: string
        physicalCounty:
          description: County for the physical address.
          example: Dorset
          type: string
        physicalPostCode:
          description: Postcode or zip code for the physical address.
          example: EC2 3YP
          type: string
        mailingAddressLine1:
          description: First line of the mailing address.
          example: 15 Wiltshire Avenue
          type: string
        mailingAddressLine2:
          description: Second line of the mailing address.
          example: South Park
          type: string
        mailingCity:
          description: City for the mailing address.
          example: Poole
          type: string
        mailingStateProvince:
          description: State or province for the mailing address.
          example: New York
          type: string
        mailingCounty:
          description: County for the mailing address.
          example: Hampshire
          type: string
        mailingPostCode:
          description: Postcode or zip code for the mailing address.
          example: BH18 8EJ
          type: string
        phone1Label:
          description: Label for the first telephone number.
          example: Home
          type: string
        phone1Country:
          description: ISO country code for the first telephone number.
          example: 44
          type: integer
        phone1Area:
          description: Area number for the first telephone number.
          example: 202
          type: integer
        phone1Number:
          description: Local part of the first telephone number.
          example: 7379 939
          type: string
        phone1Notes:
          description: Optional notes for the first telephone number.
          example: null
          type: string
        phone2Label:
          description: Label for the second telephone number.
          example: Office
          type: string
        phone2Country:
          description: ISO country code for the second telephone number.
          example: 44
          type: integer
        phone2Area:
          description: Area number for the second telephone number.
          example: 202
          type: integer
        phone2Number:
          description: Local part of the second telephone number.
          example: 6893 378
          type: string
        phone2Notes:
          description: Optional notes for the second telephone number.
          example: null
          type: string
        phone3Label:
          description: Label for the third telephone number.
          example: Mobile
          type: string
        phone3Country:
          description: ISO country code for the third telephone number.
          example: 44
          type: integer
        phone3Area:
          description: Area number for the third telephone number.
          example: 204
          type: integer
        phone3Number:
          description: Local part of the third telephone number.
          example: 0279 6394
          type: string
        phone3Notes:
          description: Optional notes for the third telephone number.
          example: null
          type: string
        phone4Label:
          description: Label for the fourth telephone number.
          example: Holiday home
          type: string
        phone4Country:
          description: ISO country code for the fourth telephone number.
          example: 44
          type: integer
        phone4Area:
          description: Area number for the fourth telephone number.
          example: 393
          type: integer
        phone4Number:
          description: Local part of the fourth telephone number.
          example: 0921 832
          type: string
        phone4Notes:
          description: Optional notes for the fourth telephone number.
          example: Only during summer months.
          type: string
        fax:
          description: Fax number.
          example: 202 3782 838
          type: string
        sms:
          description: Number for SMS messaging.
          example: 93 382 2223
          type: string
        email:
          description: Email address.
          example: james.bond@mi5.co.uk
          type: string
        website:
          description: Website address (Url).
          example: www.myorganisation.com
          type: string
        occupation:
          description: Occupation.
          example: Dentist
          type: string
        taxNumber:
          description: Tax number.
          example: NH838-23M
          type: string
        birthTimestamp:
          description: Date of birth.
          example: 23-May-1987
          type: string
          format: date
        deathTimestamp:
          description: Date of death.
          example: 09-Dec-2020
          type: string
          format: date
        maritalStatus:
          description: Marital status.
          example: Married
          type: string
        gender:
          description: Gender.
          enum:
            - M
            - F
          example: M
          type: string
        genderTypeName:
          description: Gender type name.
          example: Transgender
          type: string
        isDeceased:
          description: Indicates if dead.
          enum:
            - T
            - F
          example: F
          type: string
        dateOfBirthStatus:
          description: Status for date of birth.
          enum:
            - Known
            - Estimate
            - Not stated
            - Unknown
          default: Known
          example: Known
          type: string
        countryIdOfBirth:
          description: 2 character ISO country code.
          example: NZ
          type: string
        modifiedTimestamp:
          description: Date and time of last modification.
          example: 2023-11-08T17:17:29+13:00
          type: string
          format: timestamp
        createdTimestamp:
          description: Date and time of record creation.
          example: 2019-11-05T14:23:48+13:00
          type: string
          format: timestamp
        amlStatus:
          description: Current AML status.
          enum:
            - Not started
            - In progress
            - Signed off
          default: Not started
          example: In progress
          type: string
        amlProgress:
          description: Progress of the AML process expressed as a percentage.
          example: 75
          type: integer
          default: 0
        amlRisk:
          description: AML risk profile.
          enum:
            - Low
            - Medium
            - High
            - Unknown
          default: Unknown
          example: Medium
          type: string
        amlNote:
          description: AML notes.
          example: Successfully processed.
          type: string
        importExternalReference:
          description: Used when importing data into Actionstep from a third-party data source.
          example: DDH-3838939-333
          type: string
        links:
          $ref: '#/components/schemas/CreateParticipantsLinks'

    CreateParticipantsLinks:
      type: object
      properties:
        physicalCountry:
          description: The 2 character ISO code for the country.
          example: NZ
          type: string
        mailingCountry:
          description: The 2 character ISO code for the mailing country.
          example: NZ
          type: string
        division:
          description: Unique identifier of the division to which the participant is associated.
          example: 1
          type: integer

    UpdateParticipant:
      type: object
      properties:
        isCompany:
          description: Indicates if the participant is an individual or a company/organisation.
          example: F
          type: string
        companyName:
          description: Company or organisation name.
          example: Actionstep
          type: string
        salutation:
          description: Salutation.
          example: Mrs
          type: string
        firstName:
          description: First name.
          example: James
          type: string
        middleName:
          description: Middle name.
          example: Edward
          type: string
        lastName:
          description: Last name.
          example: Bond
          type: string
        suffix:
          description: Name suffix.
          example: Jnr
          type: string
        preferredName:
          description: Preferred name.
          example: 007
          type: string
        physicalAddressLine1:
          description: First line of the physical address.
          example: MI5 House
          type: string
        physicalAddressLine2:
          description: Second line of the physical address.
          example: South Bank
          type: string
        physicalCity:
          description: City for the physical address.
          example: London
          type: string
        physicalStateProvince:
          description: State or province for the physical address.
          example: Florida
          type: string
        physicalCounty:
          description: County for the physical address.
          example: Dorset
          type: string
        physicalPostCode:
          description: Postcode or zip code for the physical address.
          example: EC2 3YP
          type: string
        mailingAddressLine1:
          description: First line of the mailing address.
          example: 15 Wiltshire Avenue
          type: string
        mailingAddressLine2:
          description: Second line of the mailing address.
          example: South Park
          type: string
        mailingCity:
          description: City for the mailing address.
          example: Poole
          type: string
        mailingStateProvince:
          description: State or province for the mailing address.
          example: New York
          type: string
        mailingCounty:
          description: County for the mailing address.
          example: Hampshire
          type: string
        mailingPostCode:
          description: Postcode or zip code for the mailing address.
          example: BH18 8EJ
          type: string
        phone1Label:
          description: Label for the first telephone number.
          example: Home
          type: string
        phone1Country:
          description: ISO country code for the first telephone number.
          example: 44
          type: integer
        phone1Area:
          description: Area number for the first telephone number.
          example: 202
          type: integer
        phone1Number:
          description: Local part of the first telephone number.
          example: 7379 939
          type: string
        phone1Notes:
          description: Optional notes for the first telephone number.
          example: null
          type: string
        phone2Label:
          description: Label for the second telephone number.
          example: Office
          type: string
        phone2Country:
          description: ISO country code for the second telephone number.
          example: 44
          type: integer
        phone2Area:
          description: Area number for the second telephone number.
          example: 202
          type: integer
        phone2Number:
          description: Local part of the second telephone number.
          example: 6893 378
          type: string
        phone2Notes:
          description: Optional notes for the second telephone number.
          example: null
          type: string
        phone3Label:
          description: Label for the third telephone number.
          example: Mobile
          type: string
        phone3Country:
          description: ISO country code for the third telephone number.
          example: 44
          type: integer
        phone3Area:
          description: Area number for the third telephone number.
          example: 204
          type: integer
        phone3Number:
          description: Local part of the third telephone number.
          example: 0279 6394
          type: string
        phone3Notes:
          description: Optional notes for the third telephone number.
          example: null
          type: string
        phone4Label:
          description: Label for the fourth telephone number.
          example: Holiday home
          type: string
        phone4Country:
          description: ISO country code for the fourth telephone number.
          example: 44
          type: integer
        phone4Area:
          description: Area number for the fourth telephone number.
          example: 393
          type: integer
        phone4Number:
          description: Local part of the fourth telephone number.
          example: 0921 832
          type: string
        phone4Notes:
          description: Optional notes for the fourth telephone number.
          example: Only during summer months.
          type: string
        fax:
          description: Fax number.
          example: 202 3782 838
          type: string
        sms:
          description: Number for SMS messaging.
          example: 93 382 2223
          type: string
        email:
          description: Email address.
          example: james.bond@mi5.co.uk
          type: string
        website:
          description: Website address (Url).
          example: www.myorganisation.com
          type: string
        occupation:
          description: Occupation.
          example: Dentist
          type: string
        taxNumber:
          description: Tax number.
          example: NH838-23M
          type: string
        birthTimestamp:
          description: Date of birth.
          example: 23-May-1987
          type: string
          format: date
        deathTimestamp:
          description: Date of death.
          example: 09-Dec-2020
          type: string
          format: date
        maritalStatus:
          description: Marital status.
          example: Married
          type: string
        gender:
          description: Gender.
          enum:
            - M
            - F
          example: M
          type: string
        genderTypeName:
          description: Gender type name.
          example: Transgender
          type: string
        isDeceased:
          description: Indicates if dead.
          enum:
            - T
            - F
          example: F
          type: string
        dateOfBirthStatus:
          description: Status for date of birth.
          enum:
            - Known
            - Estimate
            - Not stated
            - Unknown
          default: Known
          example: Known
          type: string
        countryIdOfBirth:
          description: 2 character ISO country code.
          example: NZ
          type: string
        modifiedTimestamp:
          description: Date and time of last modification.
          example: 2023-11-08T17:17:29+13:00
          type: string
          format: timestamp
        createdTimestamp:
          description: Date and time of record creation.
          example: 2019-11-05T14:23:48+13:00
          type: string
          format: timestamp
        amlStatus:
          description: Current AML status.
          enum:
            - Not started
            - In progress
            - Signed off
          default: Not started
          example: In progress
          type: string
        amlProgress:
          description: Progress of the AML process expressed as a percentage.
          example: 75
          type: integer
          default: 0
        amlRisk:
          description: AML risk profile.
          enum:
            - Low
            - Medium
            - High
            - Unknown
          default: Unknown
          example: Medium
          type: string
        amlNote:
          description: AML notes.
          example: Successfully processed.
          type: string
        importExternalReference:
          description: Used when importing data into Actionstep from a third-party data source.
          example: DDH-3838939-333
          type: string
        links:
          $ref: '#/components/schemas/UpdateParticipantsLinks'

    UpdateParticipantsLinks:
      type: object
      properties:
        physicalCountry:
          description: The 2 character ISO code for the country.
          example: NZ
          type: string
        mailingCountry:
          description: The 2 character ISO code for the mailing country.
          example: NZ
          type: string
        division:
          description: Unique identifier of the division to which the participant is associated.
          example: 1
          type: integer

  requestBodies:
    CreateParticipant:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateParticipant'

    UpdateParticipant:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateParticipant'
