Data schema

Income and Employment report combines verification, employment, employer and employee identity information. Go to Income and Employment report in API reference to see an example of a response in JSON.

Available data:

Sample response

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "refresh_status": "new",
  "employments": [
    {
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "job_title": "PR associate",
      "job_type": "F",
      "start_date": "2018-01-01",
      "end_date": "2019-08-24",
      "external_last_updated": "2019-08-24",
      "original_hire_date": "2017-06-21",
      "is_active": false,
      "dates_from_statements": false,
      "derived_fields": [
        "is_active"
      ],
      "missing_data_fields": [
        "w2s"
      ],
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "middle_initials": "K",
        "ssn": "123456789",
        "email": "[email protected]",
        "date_of_birth": "1992-03-03",
        "home_address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210"
        }
      },
      "company": {
        "name": "Facebook Demo",
        "address": {
          "street": "1 Hacker Way",
          "city": "Menlo Park",
          "state": "CA",
          "zip": "94025"
        },
        "phone": "6503087300"
      },
      "income": "70000.00",
      "income_unit": "YEARLY",
      "pay_frequency": "M",
      "manager_name": "Jenny McDouglas",
      "statements": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "pay_date": "2018-05-15",
          "net_pay": "11500.32",
          "net_pay_ytd": "31980.64",
          "gross_pay": "13900.11",
          "gross_pay_ytd": "49200.00",
          "bonus": "100.00",
          "commission": "12000.00",
          "hours": "40.00",
          "basis_of_pay": "S",
          "period_start": "2018-05-01",
          "period_end": "2018-05-15",
          "regular": "1695.11",
          "regular_ytd": "23000.00",
          "bonus_ytd": "1000.00",
          "commission_ytd": "24000.00",
          "overtime": "45.00",
          "overtime_ytd": "500.00",
          "other_pay": "60.00",
          "other_pay_ytd": "700.00",
          "earnings": [
            {}
          ],
          "earnings_ytd": [
            {}
          ],
          "deductions": [
            {}
          ],
          "deductions_ytd": [
            {}
          ],
          "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/paystub_sample.pdf"
        }
      ],
      "annual_income_summary": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "year": 2018,
          "regular": "23000.00",
          "bonus": "1000.00",
          "commission": "24000.00",
          "overtime": "500.00",
          "other_pay": "700.00",
          "net_pay": "31980.64",
          "gross_pay": "49200.00"
        }
      ],
      "bank_accounts": [
        {
          "account_number": "1234567890",
          "routing_number": "123456789",
          "account_name": "My Bank",
          "account_type": "C",
          "deposit_type": "A",
          "deposit_value": "200.00",
          "bank_name": "TD Bank"
        }
      ],
      "annual_salary": "70000.00",
      "hourly_salary": "36.40",
      "w2s": [
        {
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/W2_sample.pdf",
          "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
          "year": 2020
        }
      ]
    }
  ],
  "provider": "adp"
}

Verification data

Data associated with employment and income verification.

Name

Type

Description

id

string

Unique ID of the report

status

string

Task status from the Task Lifecycle

completed_at

string

Timestamp of report completion

access_token

string

access_tokenaccess_token - A private token unique to a single Link. Used to access Link data and initiate any actions using the same Link for a LinkLink - A connection to a payroll provider used to retrieve payroll data. to payroll provider

tracking_info

string

Any string value provided by you when bridge_token was created

refresh_status

string

Status of most recent refresh task

provider

string

Payroll provider which user connected

employments

object

List of employments received from a payroll provider

Employment and income data

Employment and income information that was found in payroll provider records.

Name

Type

Description

id

string

Unique ID for an employment

job_title

string
(nullable)

Employee's job title

job_type

string
(nullable)

Type of employment recorded in payroll provider:
F - Full Time
P - Part Time
S - Seasonal
D - Daily (per diem)
C - Contract

start_date

string(date)

Date when employment started

end_date

string(date)
(nullable)

Date when employment ended

external_last_updated

string(date)
(nullable)

Date when employment data was last updated in payroll provider

original_hire_date

string(date)
(nullable)

Date when employee was originally hired.

is_active

boolean
(nullable)

Indicates whether the employment is still active

dates_from_statements

boolean
(nullable)

Indicates whether employee's hire and/or termination dates were derived from first/last pay statements

derived_fields

object
(nullable)

Array of derived fields

missing_data_fields

object
(nullable)

List of data fields which are missing in the payroll API response

income

string(decimal)
(nullable)

Income amount not including commission or bonuses

income_unit

string
(nullable)

Pay interval for income:
YEARLY - Annual
MONTHLY - Monthly
WEEKLY - Weekly
DAILY - Daily
HOURLY - Hourly

pay_frequency

string
(nullable)

Pay frequency:
M - Monthly
SM - Semi-Monthly
BW - Bi-Weekly
W - Weekly

manager_name

string
(nullable)

Supervisor's name

company

object
(nullable)

Employer information

profile

object
(nullable)

Identity information

annual_income_summary

object
(nullable)

Annual income summary based on last paystub of the year

statements

object
(nullable)

List of paystubs found in the payroll account

w2s

object
(nullable)

List of W-2 forms found in the payroll account

bank_accounts

object
(nullable)

List of bank accounts linked to the payroll account and allocations for direct deposit

annual_salary
(Deprecated)

string(decimal)
(nullable)

Annual income

hourly_salary
(Deprecated)

string(decimal)
(nullable)

Hourly income

Employer data

Information about all employers that were found in payroll provider records.

Name

Type

Description

name

string

Employer name

address

object
(nullable)

Employer address

street

string
(nullable)

Employer street

city

string
(nullable)

Employer city

state

string
(nullable)

Employer state

zip

string
(nullable)

Employer zip code

phone

string
(nullable)

Employer phone number

Identity data

Employee's personal information found in payroll provider.

Name

Type

Description

first_name

string

First name

last_name

string

Last name

middle_initials

string
(nullable)

Middle initials

ssn

string
(nullable)

Social security number (Full or last 4 digits)

email

string(email)
(nullable)

Personal or work email address

date_of_birth

string(date)
(nullable)

Date of birth

home_address

object
(nullable)

Home address

street

string
(nullable)

Street

city

string
(nullable)

City

state

string
(nullable)

State

zip

string
(nullable)

Zip code

Annual income summary

Annual income summary based on the last paystub of the year.

Name

Type

Description

id

string

Unique ID

year

integer

Year

regular

string(decimal)
(nullable)

Regular salary

bonus

string(decimal)
(nullable)

Bonuses

commission

string(decimal)
(nullable)

Commissions

overtime

string(decimal)
(nullable)

Overtime

other_pay

string(decimal)
(nullable)

All other type of income

gross_pay

string(decimal)
(nullable)

Gross income

net_pay

string(decimal)
(nullable)

Net income

Statements

Information found on a paystub

Name

Type

Description

id

string
(nullable)

Unique ID

pay_date

string(date)

Pay Date

period_start

string(date)
(nullable)

Period start

period_end

string(date)
(nullable)

Period end

basis_of_pay

string
(nullable)

Basis of pay:
S - Salary
H - Hourly
W - Weekly

gross_pay

string(decimal)
(nullable)

Gross pay

gross_pay_ytd

string(decimal)
(nullable)

Gross pay year to date

net_pay

string(decimal)
(nullable)

Net pay

net_pay_ytd

string(decimal)
(nullable)

Net pay year to date

regular

string(decimal)
(nullable)

Regular pay

regular_ytd

string(decimal)
(nullable)

Regular pay year to date

bonus

string(decimal)
(nullable)

Bonuses

bonus_ytd

string(decimal)
(nullable)

Bonuses year to date

commission

string(decimal)
(nullable)

Commissions

commission_ytd

string(decimal)
(nullable)

Commission year to date

overtime

string(decimal)
(nullable)

Overtime pay

overtime_ytd

string(decimal)
(nullable)

Overtime pay year to date

other_pay

string(decimal)
(nullable)

Sum of all other types of income

other_pay_ytd

string(decimal)
(nullable)

Year to date sum of all other types of income

earnings

object
(nullable)

Earnings for this pay cycle by type

earnings_ytd

object
(nullable)

Earnings year to date by type

deductions

object
(nullable)

Deductions for this pay cycle by type

deductions_ytd

object
(nullable)

Deductions year to date by type

md5sum

string(string)
(nullable)

MD5 hash value computed based on the file content

file

string(uri)
(nullable)

Link to a pay stub file (format is specified in the content-type)

Example of a paystub file:

Earnings

Earnings and earnings_ytd field of the Statement object is an array that contains all earnings. Supported categories are: regular, bonus, commission, overtime, other_pay. Sample response:

[
  {
    "name": "Regular",
    "amount": "38072.0",
    "category": "regular"
  },
  {
    "name": "Bonus",
    "amount": "10000.0",
    "category": "bonus"
  }
]

Deductions

Deductions and deductions_ytd field of the Statement object is an array that contains all deductions. Supported categories are: memo, medicare, retirement, benefit, socialsec, federal, state, garnishment, local, other. Sample response:

[
  {
    "amount": "127.01",
    "category": "socialsec",
    "name": "Social Security Tax"
  },
  {
    "amount": "46.23",
    "category": "state",
    "name": "VA State Income Tax"
  },
  {
    "amount": "29.7",
    "category": "medicare",
    "name": "Medicare Tax"
  }
]

W-2s

List W-2s found in the payroll account

Name

Type

Description

year

integer

Year of W-2

md5sum

string
(nullable)

MD5 hash value computed based on the file content

file

string(uri)

Link to a W2 report file (format is specified in the content-type)

Example of W-2 file:

Bank accounts

Information about bank accounts connected to the payroll account and direct deposit allocations for each of the accounts.

Name

Type

Description

account_number

string

Account number

routing_number

string
(nullable)

Routing number

account_name

string
(nullable)

User friendly account name

bank_name

string
(nullable)

Bank name

account_type

string
(nullable)

Account type:
C - Checking account
S - Savings account

deposit_type

string
(nullable)

Deposit type:
E - Entire paycheck
P - Percentage of the paycheck
A - Fixed amount from the paycheck

deposit_value

string(decimal)
(nullable)

Deposit value

PDF report

Citadel API automatically generates a report that combines information for income and employment verification in PDF and available to download after full_parse.


Did this page help you?