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

# get a list of persons

> Returns a list of persons corresponding to the search criterias.

By default, only the ids of the objects are returned.

A complete snaphost of the object can be returned using the view parameter.

Results are paginated.




## OpenAPI

````yaml /api-reference/persons-sites-service-offers.yaml get /persons
openapi: 3.0.3
info:
  title: Person, Site and Service Offer lifecycle
  description: >
    This API manages the lifecycle of persons, sites and service offers as
    described
    [here](https://datanumia.stoplight.io/docs/DatanumiaHome/YXBpOjQ0ODQzMjMy-person-site-and-service-offer-lifecycle)

    Please refer to the following link to get a better understanding of the
    [core
    concepts](https://datanumia.stoplight.io/docs/DatanumiaHome/ZG9jOjM4MDg2NDE5-core-concepts)
    of the Home platform.


    <b>Important notice with regard to those APIs:</b>

    - When subscribing or deleting multiple subscribed offers on a site or
    subscribed offers on multiple sites please provide all sites and subscribe
    offer data in a single POST subscriptions call.

    - They are idempotent. Launching multiple times the same operation will lead
    to the same result

    - They require a complete snapshot of all the objects involved in the
    operation. Those new objects overwrite the existing one. In other words,
    missing properties will be considered empty or null when operations will be
    executed on existing person/site objects
  termsOfService: TODO
  contact:
    email: api@datanumia.com
  version: 2.0.0
servers:
  - url: https://api.home.datanumia.com/api/v2
    description: Production Server
security: []
paths:
  /persons:
    get:
      tags:
        - persons
      summary: get a list of persons
      description: >
        Returns a list of persons corresponding to the search criterias.


        By default, only the ids of the objects are returned.


        A complete snaphost of the object can be returned using the view
        parameter.


        Results are paginated.
      operationId: getMultiplePersons
      parameters:
        - name: page
          in: query
          description: the page to be fetched. Default value is 0
          example: 0
          schema:
            type: integer
        - name: size
          in: query
          description: the page size to be fetched. Default value is 100. Max value is 100
          example: 0
          schema:
            type: integer
            default: 100
            maximum: 100
        - name: personIds
          in: query
          description: the ids of the persons to fetch
          example: personId1,personId2
          schema:
            type: string
        - name: personCustomerIds
          in: query
          description: the customer ids of the persons to fetch
          example: personCustomerId1,personCustomerId2
          schema:
            type: string
        - name: beginTs
          in: query
          description: >
            Define the start timestamp of the range to reduce the number of
            persons returned.


            Person objects modified within the range are returned.


            The supported format is as defined by RFC 3339, section 5.6
            restricted to : full-date'T'partial-time'Z'


            Default is now -7 days. Period between beginTs and endTs is at most
            30 days.
          schema:
            type: string
            default: today at midnight minus 7 days
            format: date-time
          example: '2021-07-21T00:00:00Z'
        - name: endTs
          in: query
          description: >
            Define the end timestamp of the range to reduce the number of
            persons returned.


            Person objects modified within the range are returned.


            The supported format is as defined by RFC 3339, section 5.6
            restricted to : full-date'T'partial-time'Z'


            Default is now. Period between beginTs and endTs is at most 30 days.
          schema:
            type: string
            default: start of current day at midnight
            format: date-time
          example: '2021-07-22T00:00:00Z'
        - name: view
          in: query
          required: false
          description: >
            By default, the overview mode is delivered, only the ids of the
            objects are returned.

            A complete snaphost of the object can be returned using the details
            parameter.
          schema:
            type: string
            enum:
              - overview
              - details
            default: overview
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonsList'
        '400':
          description: Functional Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorCode: INVALID_AUTHORIZATION_HEADER_VALUE
                errorDescription: The Authorization header is invalid
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorCode: ACCESS_DENIED
                errorDescription: >-
                  The Authorization token does not have permission to the
                  resource
        '500':
          description: Server error
          content: {}
      security:
        - Bearer:
            - home:referential:persons:read
components:
  schemas:
    PersonsList:
      required:
        - page
        - _links
        - _embedded
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/PersonsListLinks'
        page:
          $ref: '#/components/schemas/Page'
        _embedded:
          $ref: '#/components/schemas/PersonsListEmbedded'
    ErrorResponse:
      required:
        - errorCode
        - errorDescription
      type: object
      properties:
        errorCode:
          description: The error code. Refer to the table bellow
          type: string
        errorDescription:
          type: string
          description: The error description
      description: ErrorResponse
    PersonsListLinks:
      required:
        - first
        - prev
        - self
        - next
        - last
      type: object
      properties:
        first:
          $ref: '#/components/schemas/PersonsListLinkFirst'
        prev:
          $ref: '#/components/schemas/PersonsListLinkPrev'
        self:
          $ref: '#/components/schemas/PersonsListLinkSelf'
        next:
          $ref: '#/components/schemas/PersonsListLinkNext'
        last:
          $ref: '#/components/schemas/PersonsListLinkLast'
    Page:
      required:
        - size
        - totalElements
        - totalPages
        - number
      type: object
      properties:
        totalElements:
          type: integer
          description: number of items in the result
          example: 122
        totalPages:
          type: integer
          description: number of pages in the result
          example: 2
        number:
          type: integer
          description: current page returned
          example: 1
        size:
          type: integer
          description: page size
          example: 100
    PersonsListEmbedded:
      required:
        - persons
      type: object
      properties:
        persons:
          type: array
          items:
            $ref: '#/components/schemas/PersonData'
    PersonsListLinkFirst:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/persons?page=0&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    PersonsListLinkPrev:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/persons?page=0&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    PersonsListLinkSelf:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/persons?page=1&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    PersonsListLinkNext:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/persons?page=1&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    PersonsListLinkLast:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/persons?page=1&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    PersonData:
      required:
        - ts
        - ids
      type: object
      properties:
        ts:
          type: string
          description: |
            description: |
              The last modification date of the object as defined by RFC 3339, section 5.6 using the following format: full-date'T'partial-time'Z'
          format: date-time
          example: '2017-07-21T17:32:28Z'
        ids:
          $ref: '#/components/schemas/PersonIds'
        content:
          $ref: '#/components/schemas/PersonContent'
        _links:
          $ref: '#/components/schemas/PersonLinks'
        _embedded:
          $ref: '#/components/schemas/PersonEmbedded'
    PersonIds:
      required:
        - personId
        - personCustomerId
      type: object
      properties:
        personId:
          description: >-
            the id of the person object. It is the id from the Home perspective,
            not the external id one
          type: string
          example: personId1
          pattern: '[A-Za-z0-9-_]+'
        personCustomerId:
          type: string
          description: Your person identifier. This id is unique.
          pattern: '[A-Za-z0-9-_]+'
          example: person-45634
    PersonContent:
      description: Data contained within a Person object
      type: object
      properties:
        title:
          type: string
          example: Mme
          pattern: |
            ^([\p{L}\s.,;-]{0,10})$
        firstName:
          type: string
          pattern: |
            ^(.{0,100})$
          example: Jane
        lastName:
          type: string
          pattern: |
            ^(.{0,100})$
          example: Doe
        address:
          $ref: '#/components/schemas/PersonAddress'
        mobile:
          description: phone number in international format
          type: string
          pattern: |
            ^\+(?:[0-9] ?){6,14}[0-9]$
          example: '+33638854792'
        email:
          type: string
          description: >-
            email address respecting the OWASP definition :
            https://owasp.org/www-community/OWASP_Validation_Regex_Repository
          pattern: >
            (?=.{0,100}$)(^[a-zA-Z0-9_+&*-]+(?:\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,7})
          example: api@datanumia.com
    PersonLinks:
      required:
        - self
      type: object
      properties:
        self:
          $ref: '#/components/schemas/PersonLinkSelf'
    PersonEmbedded:
      type: object
      properties:
        sites:
          type: array
          items:
            $ref: '#/components/schemas/SiteLinks'
    PersonAddress:
      description: Address.
      type: object
      properties:
        streetNumberAndName:
          type: string
          example: 4 bis place des vosges
          pattern: ^(.{0,70})$
        streetAdditionalInfo:
          type: string
          example: BP 90137 44701
          pattern: ^(.{0,50})$
        locationAdditionalInfo:
          type: string
          example: Batiment B
          pattern: ^(.{0,40})$
        zipCode:
          type: string
          example: '92400'
          pattern: ^(.{0,20})$
        city:
          type: string
          example: Courbevoie
          pattern: ^(.{0,50})$
        country:
          type: string
          example: France
          pattern: ^(.{0,30})$
    PersonLinkSelf:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: https://<DATANUMIA_ROOT_URL>/persons/{person-id}
    SiteLinks:
      required:
        - _links
      type: object
      properties:
        self:
          $ref: '#/components/schemas/SiteLinkSelf'
    SiteLinkSelf:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: https://<DATANUMIA_ROOT_URL>/sites/{site-id}
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````