openapi: 3.0.0 info: title: Identities API version: '2.0' description: Profile and employment information. security: - basicAuth: [] paths: /v2/identities/{id}: get: summary: Retrieve an identity description: Retrieves an identity object. parameters: - in: path name: id schema: type: string format: uuid required: true description: ID of the identity object to be retrieved. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Identity' example: id: 0153b145-7ab9-bea2-cc16-a8b71328942f account: 0187c66e-e7e5-811c-b006-2232f00f426a address: city: New York line1: 852 North W St line2: Apt 221 state: NY country: US postal_code: '10014' first_name: Sarah last_name: Longfield full_name: Sarah Longfield birth_date: '1980-10-30' email: '[email protected]' phone_number: '+12125555555' picture_url: www.argyle.com/logofoldername employment_status: active employment_type: full-time job_title: Store Manager ssn: 522-09-1191 marital_status: Married filing jointly gender: Female original_hire_date: '2019-01-03' hire_date: '2020-04-08' termination_date: null termination_reason: null employer: Whole Goods employment: 0183d52a-d3b2-331d-c753-3662a20e352b base_pay: amount: '58024.50' period: annual currency: USD pay_cycle: semimonthly platform_ids: employee_id: OB238HDW5 position_id: 6ELL4O7PM platform_user_id: JLH7B9V6O6YGN9O7 created_at: '2023-01-30T12:53:24.561594Z' updated_at: '2023-01-30T12:55:06.478699Z' metadata: {} /v2/identities: get: summary: List all identities description: Returns a paginated list of all identity objects. parameters: - in: query name: account schema: type: string format: uuid description: Filter by account ID. - in: query name: user schema: type: string format: uuid description: Filter by user ID. - in: query name: employment schema: type: string format: uuid description: Filter by employment ID. - in: query name: limit schema: type: integer description: > Number of identity objects returned per page. Default: 10. Maximum: 200. - in: query name: cursor schema: type: string description: >- The URL returned in `next` or `previous` used to retrieve another [page](/api-guide/overview#pagination) of results. responses: '200': description: '' content: application/json: schema: type: object properties: next: type: string format: uri nullable: true description: URL for the next page of results, if available. previous: type: string format: uri nullable: true description: URL for the previous page of results, if available. results: type: array items: $ref: '#/components/schemas/Identity' example: next: >- https://api-sandbox.argyle.com/v2/identities?cursor=ZXhhbXBsZV9jdXJzb3I previous: null results: - id: 0186da0b-6569-0ea0-eb50-b64e97cb29e9 account: 0186da0b-9923-0d27-4b05-6ce3b7b07b89 address: city: San Diego line1: 54 N Shea Ridge line2: null state: CA country: US postal_code: '92092' first_name: Joe last_name: Burnam full_name: Joe Burnam birth_date: '1978-08-29' email: '[email protected]' phone_number: '+12123338708' picture_url: www.argyle.com/logofoldername employment_status: active employment_type: part-time job_title: Hourly staff ssn: 301-06-1225 marital_status: Married filing jointly gender: Male original_hire_date: '2022-05-18' hire_date: '2022-05-18' termination_date: null termination_reason: null employer: Double Double employment: 0183d52a-d3b2-331d-c753-3662a20e352b base_pay: amount: '18.08' period: hourly currency: USD pay_cycle: monthly platform_ids: employee_id: 32ULINA8 position_id: 67LKUKA8 platform_user_id: '332512349952' created_at: '2023-01-31T12:13:24.561594Z' updated_at: '2023-01-31T12:45:06.478699Z' metadata: {} - id: 0353c142-4ab9-baa1-cb44-c8b51225877e account: 0185a8b8-60eb-80ca-7482-5f24504573f7 address: city: Oklahoma City line1: 312 Main Ave line2: null state: OK country: US postal_code: '73008' first_name: Bob last_name: Jones full_name: Bob Jones birth_date: '1983-07-02' email: '[email protected]' phone_number: '+13228675309' picture_url: www.argyle.com/logofoldername employment_status: active employment_type: contractor job_title: Data analyst ssn: 507-18-3058 marital_status: Single gender: Female original_hire_date: '2019-01-03' hire_date: '2021-04-08' termination_date: null termination_reason: null employer: Half Bads employment: 0183d52a-d3b2-331d-c753-3662a20e352b base_pay: amount: '39.72' period: hourly currency: USD pay_cycle: biweekly platform_ids: employee_id: bd823Lk position_id: ab3EkU2 platform_user_id: '832355' created_at: '2023-01-30T13:53:24.561594Z' updated_at: '2023-01-30T13:55:06.478699Z' metadata: {} components: securitySchemes: basicAuth: type: http scheme: basic description: Username = api_key_id, Password = api_key_secret schemas: Address: type: object properties: city: type: string description: Name of the city, town, district, or similar regional entity. example: New York line1: type: string description: Address-Line 1, usually street address or P.O. Box information. example: 852 North W St line2: type: string description: Address-Line 2, usually the apartment or unit number. example: Apt 221 state: type: string description: State, county, province, region, or equivalent. example: NY country: type: string description: > Two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format). example: US postal_code: type: string description: Zip code, or equivalent. example: '10014' BasePay: type: object properties: amount: type: string description: >- Defined pay amount per period. Does not include bonus, commission or similar incentive-based income. example: '58024.50' period: type: string enum: - hourly - daily - weekly - biweekly - semimonthly - monthly - annual - salary description: > Payment interval that specifically corresponds to the base pay `amount`. - `hourly` - `daily` - `weekly` - `biweekly` — every two weeks - `semimonthly` — twice a month - `monthly` - `annual` - `salary` — only when explicitly mentioned and no other pay period information is present example: annual currency: type: string description: > Pay currency ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code). example: USD PlatformIds: type: object properties: employee_id: type: string description: Internal user ID assigned by the employer. example: OB238HDW5 position_id: type: string description: Internal position ID assigned by the employer. example: 6ELL4O7PM platform_user_id: type: string description: ID assigned by the payroll system. example: JLH7B9V6O6YGN9O7 Identity: type: object example: id: 0153b145-7ab9-bea2-cc16-a8b71328942f account: 0187c66e-e7e5-811c-b006-2232f00f426a address: city: New York line1: 852 North W St line2: Apt 221 state: NY country: US postal_code: '10014' first_name: Sarah last_name: Longfield full_name: Sarah Longfield birth_date: '1980-10-30' email: sarah@email.com phone_number: '+12125555555' picture_url: www.argyle.com/logofoldername employment_status: active employment_type: full-time job_title: Store Manager ssn: 522-09-1191 marital_status: Married filing jointly gender: Female original_hire_date: '2019-01-03' hire_date: '2020-04-08' termination_date: null termination_reason: null employer: Whole Goods employment: 0183d52a-d3b2-331d-c753-3662a20e352b base_pay: amount: '58024.50' period: annual currency: USD pay_cycle: semimonthly platform_ids: employee_id: OB238HDW5 position_id: 6ELL4O7PM platform_user_id: JLH7B9V6O6YGN9O7 created_at: '2023-01-30T12:53:24.561Z' updated_at: '2023-01-30T12:55:06.478Z' metadata: null properties: id: type: string format: uuid description: Unique ID of the identity. example: 0153b145-7ab9-bea2-cc16-a8b71328942f account: type: string format: uuid description: ID of the account associated with the identity. example: 0187c66e-e7e5-811c-b006-2232f00f426a address: $ref: '#/components/schemas/Address' first_name: type: string description: First name of the employee. Usually the legal first name. example: Sarah last_name: type: string description: Last name of the employee. Usually the legal last name. example: Longfield full_name: type: string description: >- Full name of the employee. Sourced from payroll data if available, otherwise constructed from available names and suffixes. example: Sarah Longfield birth_date: type: string format: date description: > Date of birth in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. If values are obfuscated (rare), a dash will replace the value (e.g. --01-31 when the year is obfuscated). example: '1980-10-30' email: type: string description: Email address. example: '[email protected]' phone_number: type: string description: > Phone number [E.164](https://en.wikipedia.org/wiki/E.164) international format). example: '+12125555555' picture_url: type: string description: URL location of the user's profile image. example: www.argyle.com/logofoldername employment_status: type: string enum: - active - inactive - terminated description: > Job status of the employment relevant to the identity. - Definitions of `inactive` and `terminated` vary by Item and can overlap. - `inactive` typically indicates the employee left voluntarily, is on leave, or has not been active for a certain period of time. - `terminated` typically indicates the employee is no longer employed. Specific reasons for termination, if available, are returned in the `termination_reason` field. - We recommend using data from the `/paystubs` and `/gigs` endpoints to construct a more wholistic timeline of employment history. example: active employment_type: type: string enum: - full-time - part-time - contractor - military - benefits - seasonal - temporary - regular - other description: | Type of employment.
Employment type enum definitions - `full-time` - Employment in which an individual is regularly scheduled to work 30 or more hours per week, or meets the employer's internal threshold for a standard full-time workweek. - **Examples:** `full-time employee`, `36+ hours weekly` - `part-time` - Employment in which an individual is regularly scheduled to work fewer than 30 hours per week, or meets the employer's internal threshold for a standard part-time workweek. - **Examples:** `PT regular`, `20+ hours weekly` - `contractor` - Work performed by an individual engaged for a specific project or timeframe who is not an employee of the organization. - **Examples:** `gig worker`, `contract employee`, `contract worker`, `freelancer` - `military` - Compensation derived from active-duty or reserve military service. - *Automatically set for military platforms.* - `benefits` - Non-wage compensation or government-issued assistance. - *Automatically set for benefits platforms.* - `seasonal` - Employment that occurs at approximately the same time each year, typically lasting six months or less. - **Examples:** `seasonal on-call`, `seasonal part-time`, `peak seasonal` - `temporary` - Short-term employment with a defined end date, usually lasting one year or less. - **Examples:** `internship`, `substitute employee`, `temporary full-time`, `temporary part-time` - `regular` - Ongoing employment with no specified end date that does not fall into more specialized categories. - **Examples:** `permanent`, `W-2`, `salaried` - `other` - Work or income that does not fit standard classifications. - **Examples:** `variable`, `casual`, `employee`, `PRN (on-call)`
example: full-time job_title: type: string description: Job title. example: Store Manager ssn: type: string description: Social Security number. example: 522-09-1191 marital_status: type: string description: Marital status. example: Married filing jointly gender: type: string description: Gender. example: Female original_hire_date: type: string format: date description: > Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) of the user's **earliest** employment start date. example: '2019-01-03' hire_date: type: string format: date description: > Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) of the user's **most recent** employment start date. `hire_date` may differ from `original_hire_date` due to a promotion, a re-hiring event, or similar. example: '2020-04-08' termination_date: type: string format: date nullable: true description: >- Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the user was terminated. example: null termination_reason: type: string nullable: true description: Reason for termination. example: null employer: type: string description: Name of the employer. example: Whole Goods employment: type: string description: > [Employment](/api-reference/employments) ID. Can be used as a filter when [listing identities](/api-reference/identities/list-all-identities). example: 0183d52a-d3b2-331d-c753-3662a20e352b base_pay: $ref: '#/components/schemas/BasePay' pay_cycle: type: string enum: - daily - weekly - biweekly - semimonthly - monthly - quarterly description: | Payment frequency. - `daily` - `weekly` - `biweekly` — every two weeks - `semimonthly` — twice a month - `monthly` - `quarterly` example: semimonthly platform_ids: $ref: '#/components/schemas/PlatformIds' created_at: type: string format: date-time description: > Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the identity object was created. example: '2023-01-30T12:53:24.561594Z' updated_at: type: string format: date-time description: > Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when a property value of the identity object most recently changed. example: '2023-01-30T12:55:06.478699Z' metadata: type: object description: Additional, non-categorized information. example: {}