ADP DataCloud Employment and Income Verification API - Guide Published on Jun 16, 2021 10:11AM
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Guide
ADP DataCloud
Employment and
Income Verification API
Published on
Jun 16, 2021 10:11AM
Last modified
Aug 03, 2021 10:05AM
1ADP Copyright Information
ADP, the ADP logo, and Always Designing for People are trademarks of ADP, Inc.
Windows is a registered trademark of the Microsoft Corporation.
All other trademarks are the property of their respective owners.
Copyright © 2021 ADP, Inc. ADP Proprietary and Confidential - All Rights Reserved. These materials
may not be reproduced in any format without the express written permission of ADP, Inc.
These materials may not be reproduced in any format without the express written permission of ADP,
Inc. ADP provides this publication “as is” without warranty of any kind, either expressed or implied,
including, but not limited to, the implied warranties of merchantability or fitness for a particular
purpose. ADP is not responsible for any technical inaccurancies or typographical errors which may be
contained in this publication. Changes are periodically made to the information herein, and such
changes will be incorporated in new editions of this publication. ADP may make improvements and/or
changes in the product and/or the programes described in this publication.
Published on
Jun 16, 2021 10:11AM
Last modified
Aug 03, 2021 10:05AM
2Table of Contents
Chapter 1
API Onboarding Steps
Summary
Step 1: Get Access to the ADP Developer Portal
Step 2: Sandbox Agreement
Step 3: Development Credentialing
Step 4: Business Term Sheet
Step 5: Letter of Intent (LOI)
Step 6: FCRA Questionnaire
Step 7: Global Security Organization (GSO), Third-Party Risk Assessment (TPRA), &
Privacy Reviews
Step 8: Master Services Agreement (MSA) & Statement of Work (SOW)
Step 9: Production Credentialing
Step 10: Billing / Invoicing Set Up
Chapter 2
API Overview
Summary
API Overview Table
Identity Verification
Employment Verification
Employment & Income Verification (YTD)
Employment & Income Verification (Detailed)
Chapter 3
Rate Limits
Rate Limits
Chapter 4
Identity Verification
Endpoint
Summary
Returns
Sample Response
Criterias & Exceptions
Errors
Input
3Sample Input
Chapter 5
Employment Verification
Endpoint
Summary
Returns
Sample Response
Criterias & Exceptions
Errors
Input
Sample Input
Chapter 6
Employment & Income Verification (YTD)
Endpoint
Summary
Returns
Sample Response
Criterias & Exceptions
Errors
Input
Sample Input
Chapter 7
Employment & Income Verification (Detailed Basic)
Endpoint
Summary
Returns
Sample Response
Criterias & Exceptions
Errors
Input
Sample Input
Chapter 8
Employment & Income Verification (Detailed Enhanced)
Endpoint
Summary
Returns
Sample Response
Criterias & Exceptions
Errors
Input
Sample Input
Chapter 9
FAQs
Input
4API General Info and Structure
Data: Earnings
Data: Refresh Rate
Data: Other
Chapter 10
API Production Support
Summary
Emergency Connectivity Issues
Data Disputes
General Questions
5Chapter 1
API Onboarding Steps
Summary
The purpose of this page is to share the necessary steps to onboard the ADP DataCloud Employment and Income Verification APIs from
development to production. It serves as a guide to inform what to expect along the way, and who are the key stakeholders involved in each of
these steps.
Pre-requisite: before any of the below steps can be taken, the following 2 pre-requisites must be completed:
1. Register your organization via our partner program form, if not done so previously
2. Sign the mutual non-disclosure agreement (MNDA). The MNDA will be provided by your ADP business development contact.
Step 1: Get Access to the ADP Developer Portal
Roles: Business Development, Product Development
With the MNDA signed, you'll now be able to access this guide and other supporting documentation such as specifications, FAQs, etc. that is
shown in this guide. You are free to view our specification, along with the included sample responses to get a deeper understanding of the
APIs we have available. Also, partners get access to this guide so they can better understand the steps involved to fully onboard with our APIs
Step 2: Sandbox Agreement
Roles: Business Development
Your ADP business development contact will then provide an API Sandbox Agreement to be signed. The ADP API Sandbox Agreement allows
the creation of developer credentials so that your team can play around with the APIs using dummy test data and be able to begin
development.
Step 3: Development Credentialing
Roles: Product Development
Once the Sandbox Agreement is signed, an ADP product lead will reach out to your development and product leads to obtain the name(s) of
development leads and members so that ADP can:
1. Set up a secure file sharing site to which onboarding documents can be shared, such as postman collections that includes all the endpoints
and test inputs constructed, additional dummy test inputs that provide different types of data responses to depict various scenarios, and other
supporting documentation to help your team with development.
2. Set up a private Slack Channel between development teams to answer any technical questions related to the integration. An ADP Product
Development member will provide a link to your development team to join Slack.
3. Set up and securely provide development credentials.
Development credentials are composed of a client ID and client secret, and will be securely sent by an ADP product member. In addition to
client ID and client secret, you must generate a mutual SSL certificate in order to successfully connect to our API endpoints. Instructions for
this step will be provided to you along with the credentials.
6Additional Note: our API endpoints are the same for both development and production. It is the credentials that provide access to either
dummy test data or live production data. Mutual SSL Certificates remain the same and can be reused when you later transition to production.
Step 4: Business Term Sheet
Roles: Business Development
As part of the business development effort, ADP will present a business term sheet. The business term sheet is a nonbinding agreement
setting forth the basic terms and conditions under which a partnership alliance will be made. It serves as a template to develop more detailed
legally binding documents (MSA/SOW). It is helpful to understand the different use cases and market verticals you wish to use ADP data for.
Step 5: Letter of Intent (LOI)
Roles: Business Development, Legal
The LOI is a non-binding agreement that outlines the understanding between ADP and your organization the intent to formalize into a
partnership.
Step 6: FCRA Questionnaire
Roles: Business Development, Legal
As part of the legal review process, potential partners are required to complete the FCRA Questionnaire to determine their ability to meet our
compliance requirements. This questionnaire will be provided by your business development contact. The ADP legal team will also review any
use case, process flow or interactive demonstrations to gain understanding of the potential business relationship. It is helpful if you can
provide any documentation or demos of how ADP data will be used in your product or services.
Step 7: Global Security Organization (GSO), Third-Party Risk Assessment (TPRA), & Privacy
Reviews
Roles: GSO, Legal, Business Development
All partners of ADP are required to undergo a formal securty and risk assessment, faciliated by our GSO team. Partners will be asked to
complete required security and risk questionnaires. This process can take 4-8 weeks to complete. Your ADP contact will help kick off this
process.
The Privacy Review process includes a (questionnaire) used by the Global Data Privacy and Governance team to identify and evaluate privacy
risks associated with the processing of personally identifiable information/personal data (PI).
Step 8: Master Services Agreement (MSA) & Statement of Work (SOW)
Roles: Business Development, Legal
7At this stage, ADP will provide MSA and SOW documentation for review. Once the MSA/SOW is signed by both parties, production credentials
can be generated
Step 9: Production Credentialing
Roles: Product Development
Once the MSA/SOW is signed, ADP will provide production credentials within 48-72 hours. The production credentials are a new set of client
ID and client secret, and when used will gain access to live production data. The existing mutual SSL certificate can be used with production
credentials, and the same endpoints that were used during development can be used with production credentials.
Step 10: Billing / Invoicing Set Up
Roles: Business Development, Product Development
Finally, as the last step, an ADP Product Development member will ask for the contact info of your lead business development member, to
whom invoices and billing will be addressed to. ADP will make sure to set up an account for that business development member and send an
invitation to login to finish registration.
Chapter 2
API Overview
Summary
The ADP DataCloud Employment and Income Verification APIs are composed of 5 endpoints, returning varying levels of data fit for different
types of use cases. In this chapter, you'll find an overview of the endpoints and data they return, so that it may help you choose the right
endpoint that best serves your use cases.
API Overview Table
8Identity Verification
basic/identity API - Obtains simple signal match (true or false) to indicate whether a person exists in the ADP database
Use Cases
Account creation (i.e. online banking, cell phone account, etc.) – check if an individual exists in the ADP database, and if the personal
information submitted by the individual during account creation matches with what is in the ADP database used for payroll
Employment Verification
basic/employment API - Obtains employment history for an individual (e.g. verification of employment)
Use Cases
Pre-employment screening – check if individual is employed, and obtain history of employment
Employment & Income Verification (YTD)
enhanced/employment API - Obtains employment history + annual pay summary (YTD) for an individual
Use Cases
Pre-employment screening for certain jobs (check jurisdiction restrictions) – check if individual is employed, obtain history of employment, and
YTD income
9Credit card – verification of employment and basic income summary to help confirm stated income and employment • Offers – to help target
offers and pre-qualifications to potential customers
Offers or Pre-qualification – to help target offers and pre-qualifications to potential customers
Employment & Income Verification (Detailed)
basic/employment-income API - Obtains employment history, annual pay summary (YTD), and income history (pay period details) for the
current year to date plus the last 2 full years, if available. Best used for mortgage, auto loans, personal loans where income history is needed,
but deductions are not necessary.
Use Cases
Auto loans, tenant screenings, personal loans, mortgage – check employment history and detailed pay period history for up to 3 years
enhanced/employment-income API - Obtains everything in basic/employment-income API, PLUS deductions information
Use Cases
Mortgage, government services – check employment history and detailed pay period history (with deductions information) for up to 3 years, for a
more comprehensive data set
Chapter 3
Rate Limits
Rate Limits
As with other APIs at ADP, there are limits to how many calls you're able to make within a given timeframe. They are as follows:
50 concurrent calls
300 calls per minute
Chapter 4
Identity Verification
Endpoint
POST https://api.adp.com/core/v1/associate-verifications/basic/identity
Summary
Checks if a person is a match in the ADP database, and provides a comparison of what inputs matched and didn't match. Also returns
employment summary for that individual (e.g. whether or not if there is income data available, and whether or not the individual is an active
employee)
10Returns
governmentID
id - ex. xxx-xx-0000
nameCode
code - i.e. SSN
name - i.e. Last 4 digits of SSN
identityMatchDetails
matchTypeCode - returns complete, partial, or none to indicate if supplied input matches with ADP record
matchDetails - if one or more supplied inputs (other than government ID) is not a match in ADP records, then matchDetails returns
the following:
birthDateMatch
submittedValue - birthdate specified in the input
matchIndicator - true or false whether or not the birthdate specified in the input matches with person in ADP
record
givenNameMatch
submittedValue - first name specified in the input
matchIndicator - true or false whether or not the first name specified in the input matches with person in ADP
record
scoreValue - numerical score for match between first name specified in the input and value ADP record
middleNameMatch
submittedValue - middle name specified in the input
matchIndicator - true or false whether or not the middle name specified in the input matches with person in ADP
record
scoreValue - numerical score for match between middle name specified in the input and value ADP record
familyNameMatch
submittedValue - last name specified in the input
matchIndicator - true or false whether or not the last name specified in the input matches with person in ADP
record
scoreValue - numerical score for match between last name specified in the input and value ADP record
addressMatch
lineOneMatch
submittedValue - address line one specified in the input
matchIndicator - true or false whether or not the line one of the address specified in the input matches
with person in ADP record
scoreValue - numerical score for match between address line one specified in the input and value ADP
record
lineTwoMatch
submittedValue - address line two specified in the input
matchIndicator - true or false whether or not the line two of the address specified in the input matches
with person in ADP record
scoreValue - numerical score for match between address line two specified in the input and value ADP
record
lineThreeMatch
submittedValue - address line three specified in the input
matchIndicator - true or false whether or not the line three of the address specified in the input matches
with person in ADP record
scoreValue - numerical score for match between address line three specified in the input and value ADP
record
cityMatch
submittedValue - city specified in the input
matchIndicator - true or false whether or not the city specified in the input matches with person in ADP
record
scoreValue - numerical score for match between city specified in the input and value ADP record
subdivisionCodeMatch
submittedValue - subdivision code (or state) specified in the input
11matchIndicator - true or false whether or not the state specified in the input matches with person in ADP
record
scoreValue - numerical score for match between subdivision code specified in the input and value ADP
record
postalCodeMatch
submittedValue - postal code specified in the input
matchIndicator - true or false whether or not the postal code specified in the input matches with person
in ADP record
scoreValue - numerical score for match between postal code specified in the input and value ADP record
countryCodeMatch
submittedValue - country specified in the input
matchIndicator - true or false whether or not the country code specified in the input matches with
person in ADP record
scoreValue - numerical score for match between country code specified in the input and value ADP record
depositAccountNumberMatch
last4Match - returns true if the supplied last 4 direct deposit account number in the input is a match to any last 4
direct deposit account number from the person's employment in the current year to date and the last 2 full years.
Returns null if there are no direct deposit accounts
isMostRecent - returns true or false whether or not the matched direct deposit last 4 is from the most recent
employment in ADP records
routingTransitIDLast4Match
last4Match - returns true if the supplied last 4 routing number in the input is a match to any last 4 routing number
from the person's employment in the current year to date and the last 2 full years. Returns null if there are no
routing numbers
isMostRecent - returns true or false whether or not the matched routing number last 4 is from the most recent
employment in ADP records
employmentSummary
workerStatusIsActive - returns true if the person's worker status is Active from any employer
incomeDataAvailable - returns true if income data is available for the person
Sample Response
{
"governmentID": {
"id": "xxx-xx-0000",
"nameCode": {
"code": "SSN",
"name": "Last 4 digits of SSN"
}
},
"identityMatchDetails": {
"matchTypeCode": "Partial",
"matchDetails": {
"birthDateMatch": {
"submittedValue": "1984-01-01",
"matchIndicator": true,
"scoreValue": 100
},
"givenNameMatch": {
"submittedValue": "First",
"matchIndicator": false,
"scoreValue": 86
},
"familyNameMatch": {
"submittedValue": "Last",
"matchIndicator": true,
"scoreValue": 100
}
}
}
}
12Criterias & Exceptions
If the supplied government ID (ex. SSN) is not found in ADP records, a 404 person not found will be returned
If the supplied government ID (ex. SSN) matches but the date of birth does not match, then depositAccountNumberLast4Match,
routingTransitIDLast4Match, and employmentSummary will not be returned
Errors
404 Person not found
A person was not found from the supplied government ID
400 Invalid input
Invalid market vertical. Please provide a valid market vertical.
End consumer consent not provided
Invalid government ID format. Please check and try again.
Invalid date of birth format. Please provide in the format yyyy-mm-dd
Input
requestorInfo
marketSegmentCode (string) - the market vertical in which the request is applicable to. To be provided by development contact
(Required)
verifierName (string) - the company name of the verifier (ex. the name of the lender organization) (Required)
associateVerificationRequest
governmentID (string) - SSN (9 digit) (Required)
birthDate (string) - YYYY-MM-DD (Required)
personName
familyName (string)
givenName (string)
middleName (string)
address
lineOne (string)
lineTwo (string)
lineThree (string)
cityName (string)
subdivisionCode (string)
countryCode (string)
postalCode (string)
depositAccountNumberLast4 (string)
routingTransitIDLast4 (string)
associateConsentReceivedIndicator (Required)
Sample Input
13{
"requestorInfo": {
"marketSegmentCode": "string",
"verifierName": "string"
},
"associateVerificationRequest": {
"governmentID": {
"id": "string"
},
"birthDate": "YYYY-MM-DD",
"personName": {
"givenName": "string",
"middleName": "string",
"familyName": "string"
},
"address": {
"lineOne": "string",
"lineTwo": "string",
"lineThree": "string",
"cityName": "string",
"subdivisionCode": {
"code": "string",
"name": "string",
"subdivisionType": "string"
},
"countryCode": "string",
"postalCode": "string"
},
"depositAccountNumberLast4": "string",
"routingTransitIDLast4": "string"
},
"associateConsentReceivedIndicator": true
}
Chapter 5
Employment Verification
Endpoint
POST https://api.adp.com/core/v1/associate-verifications/basic/employment
Summary
Obtains employment history for a specified person. Best used to help verify whether or not a person is employed, and which employers they
have worked for.
Can be used for: pre-employment screening
Returns
governmentID
id - ex. xxx-xx-0000
nameCode
14code - i.e. SSN
name - i.e. Last 4 digits of SSN
personalData (most recent)
personName
givenName - first name
middleName - middle name
familyName - last name
address - address
communication
telephones - phone number(s), if available
emails - email(s), if available
employmentHistory (for each employer)
asOfDate - last pay date (YYYY-MM-DD)
employerName - employer name
legalEntityID - employer legal ID, i.e. federal employer ID number (FEIN)
systemRefreshDate - date of latest data refresh (YYYY-MM-DD)
employerAddress
lineOne
lineTwo
lineThree (if applicable)
cityName
subdivisionCode1
name - i.e. CA
countryCode - i.e. US
postalCode - i.e. zip code
employmentDetail (if multiple job positions are available for same employer, they will be included here)
effectiveDate - the date which information was updated in ADP records
originalHireDate - date which employee was hired
workerStatusCode - employee status (A - Active, T - Terminated, L - Leave)
code - A, T, L
name - Active, Terminated, Leave
workLevelCode - employment type (i.e. Full-time, part-time, regular, temp, contractor)
code - Full time, Part time. For employers that use ADP Payroll HCM such as WorkForce Now, they can enter a
freeform text to denote a worker level code for the employee, of which will be provided
name - Full time, Part time. For employers that use ADP Payroll HCM such as WorkForce Now, they can enter a
freeform text to denote a worker level name for the employee, of which will be provided
payrollGroupCode - payroll group code
code - payroll group code
positionTitle - job title
positionStartDate - most recent hire date
positionEndDate - termination date
positionTenureDuration - tenure (ISO 8601)
standardHours - hours entered in the Payroll system by the employer, most often this number is hours per week. For full time
employees, in general, it is usually 40 and for part time it will reflect the hours scheduled to work per week
remunerationBasisCode - pay description
name - Salary, Hourly, Daily
payCycleCode - pay frequency
code (corresponds to the name, respectively, as in M = Monthly, S = Semi-Monthly, etc.) - M, S, B, W, D, BO, BE, Q, SA, A, 2, 4, 5
name - Monthly, Semi-Monthly, Bi-Weekly, Weekly, Daily, Bi-Weekly Odd, Bi-Weekly Even, Quarterly, Semi-Annual, Annual,
Every 2.6 wks, Every 4 wks, Every 5.2 wks
historySummary (this section provides some general information about the data returned)
availableHistorySourceCount - indicates the total number of employers which have information about the person
includedHistorySourceCount - indicates the number of employers whose data about the person was included in the response
Sample Response
15{
"governmentID": {
"id": "xxx-xx-0000",
"nameCode": {
"code": "SSN",
"name": "Last 4 digits of SSN"
}
},
"personalData": {
"personName": {
"givenName": "First",
"middleName": "Middle",
"familyName": "Last"
},
"communication": {
"telephones": [
{
"formattedNumber": 3101111111
}
],
"emails": [
{
"emailUri": "sample.email@test.com"
}
],
"internetAddresses": []
},
"address": {
"lineOne": "16 lgl",
"lineTwo": "Ui ",
"lineThree": null,
"cityName": "Cieo",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
}
},
"employmentHistory": [
{
"asOfDate": "2020-07-31",
"employerName": "Amazing Community Pharmacy LLC",
"legalEntityID": {
"legalEntityID": "111111111"
},
"systemRefreshDate": "2021-08-01",
"employerAddress": {
"lineOne": "13 EMN T 1",
"lineTwo": null,
"lineThree": null,
"cityName": "CIEO",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
},
"employmentDetail": [
{
"effectiveDate": "2019-12-23",
"originalHireDate": "2015-08-10",
"workerStatusCode": {
"code": "A",
"name": "Active"
},
"workLevelCode": {
"code": "Full time",
"name": "Full time"
},
"positionTitle": null,
"positionStartDate": "2015-08-10",
"positionEndDate": null,
"positionTenureDuration": "P4Y10M12D",
"standardHours": 0.0
}
]
},
16{
"asOfDate": "2020-06-22",
"employerName": "Soul Cafe Llc",
"legalEntityID": {
"legalEntityID": "111111111"
},
"employerAddress": {
"lineOne": "13 EMN T 1",
"lineTwo": null,
"lineThree": null,
"cityName": "CIEO",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
},
"employmentDetail": [
{
"effectiveDate": "2015-08-18",
"originalHireDate": "2015-08-10",
"workerStatusCode": {
"code": "A",
"name": "Active"
},
"workLevelCode": {
"code": "Part time",
"name": "Part time"
},
"positionTitle": null,
"positionStartDate": "2015-08-10",
"positionEndDate": null,
"positionTenureDuration": "P4Y10M12D",
"standardHours": 60.0
}
]
}
],
"historySummary": {
"availableHistorySourceCount": 2,
"includedHistorySourceCount": 2
}
}
Criterias & Exceptions
If the supplied government ID and DOB do not match to an ADP record, a 404 person not found will be returned
Errors
404 Person not found
A person was not found from the supplied government ID
400 Invalid input
Invalid market vertical. Please provide a valid market vertical.
End consumer consent not provided
Invalid government ID format. Please check and try again.
Invalid date of birth format. Please provide in the format yyyy-mm-dd
17Input
requestorInfo
marketSegmentCode (string) - the market vertical in which the request is applicable to. To be provided by development
contact (Required)
verifierName (string) - the company name of the verifier (ex. the name of the lender organization) (Required)
associateVerificationRequest
governmentID (string) - SSN (9 digit) (Required)
birthDate (string) - YYYY-MM-DD (Required)
associateConsentReceivedIndicator (Required)
Sample Input
{
"requestorInfo": {
"marketSegmentCode": "Talent",
"verifierName": "Example Verifier Company"
},
"associateVerificationRequest": {
"governmentID": {
"id": "000000000"
},
"birthDate": "1984-01-01"
},
"associateConsentReceivedIndicator": true
}
Chapter 6
Employment & Income Verification (YTD)
Endpoint
POST https://api.adp.com/core/v1/associate-verifications/enhanced/employment
Summary
Obtains employment history and annual pay summary (for the current year to date plus the last 2 full years). Best used to help verify whether
or not a person is employed, which employers they have worked for, and get a summary view of their current and past full 2 years YTD income.
Can be used for: credit card applications, pre-employment screening for certain types of jobs (jurisdiction restrictions may apply), where
employment history and income summary (YTD or annual view) is needed
Returns
governmentID
id - ex. xxx-xx-0000
nameCode
code - i.e. SSN
18name - i.e. Last 4 digits of SSN
personalData (most recent)
personName
givenName - first name
middleName - middle name
familyName - last name
address
lineOne
lineTwo
lineThree (if applicable)
cityName
subdivisionCode1
name - i.e. CA
countryCode - i.e. US
postalCode - i.e. zip code
communication
telephones - phone number(s), if available
emails - email(s), if available
employmentHistory (for each employer)
asOfDate - last pay date (YYYY-MM-DD)
employerName - employer name
legalEntityID - employer legal ID, i.e. federal employer ID number (FEIN)
systemRefreshDate - date of latest data refresh (YYYY-MM-DD)
employerAddress
lineOne
lineTwo
lineThree (if applicable)
cityName
subdivisionCode1
name - i.e. CA
countryCode - i.e. US
postalCode - i.e. zip code
employmentDetail (if multiple job positions are available for same employer, they will be included here)
effectiveDate - the date which information was updated in ADP records
originalHireDate - date which employee was hired
workerStatusCode - employee status (A - Active, T - Terminated, L - Leave)
code - A, T, L
name - Active, Terminated, Leave
workLevelCode - employment type (i.e. Full-time, part-time, regular, temp, contractor)
code - Full time, Part time. For employers that use ADP Payroll HCM such as WorkForce Now, they can enter a
freeform text to denote a worker level code for the employee, of which will be provided
name - Full time, Part time. For employers that use ADP Payroll HCM such as WorkForce Now, they can enter a
freeform text to denote a worker level name for the employee, of which will be provided
payrollGroupCode - payroll group code
code - payroll group code
positionTitle - job title
positionStartDate - most recent hire date
positionEndDate - termination date
positionTenureDuration - tenure (ISO 8601)
standardHours - hours entered in the Payroll system by the employer, most often this number is hours per week. For full time
employees, in general, it is usually 40 and for part time it will reflect the hours scheduled to work per week
remunerationBasisCode - pay description
name - Salary, Hourly, Daily
payCycleCode - pay frequency
code (corresponds to the name, respectively, as in M = Monthly, S = Semi-Monthly, etc.) - M, S, B, W, D, BO, BE, Q, SA, A, 2, 4, 5
name - Monthly, Semi-Monthly, Bi-Weekly, Weekly, Daily, Bi-Weekly Odd, Bi-Weekly Even, Quarterly, Semi-Annual, Annual,
Every 2.6 wks, Every 4 wks, Every 5.2 wks
basePayRate - base/regular pay rate
amount
19currencyCode - i.e. USD
remunerationSummary - YTD pay for the current year to date, plus last 2 full years. For the case when data is quarterly in nature (i.e.
data source only comes from tax data), then only the gross YTD will be available
payrollYear - year
baseRemunerationAmount - YTD Base
amount
currencyCode - i.e. USD
additionalRemunerations
remunerationTypeCode - YTD Bonus
amount
currencyCode - i.e. USD
remunerationTypeCode - YTD Overtime
amount
currencyCode - i.e. USD
remunerationTypeCode - YTD Others
amount
currencyCode - i.e. USD
totalAnnualRenumerationAmount - YTD Gross
amount
currencyCode - i.e. USD
netPayYTDAmount - YTD Net
amount
currencyCode - i.e. USD
historySummary (this section provides some general information about the data returned)
availableHistorySourceCount - indicates the total number of employers which have information about the person
includedHistorySourceCount - indicates the number of employers whose data about the person was included in the response
Sample Response
20{
"governmentID": {
"id": "xxx-xx-0000",
"nameCode": {
"code": "SSN",
"name": "Last 4 digits of SSN"
}
},
"personalData": {
"personName": {
"givenName": "First",
"middleName": "Middle",
"familyName": "Last"
},
"communication": {
"telephones": [
{
"formattedNumber": 3101111111
}
],
"emails": [
{
"emailUri": "sample.email@test.com"
}
],
"internetAddresses": []
},
"address": {
"lineOne": "16 lgl",
"lineTwo": "Ui ",
"lineThree": null,
"cityName": "Cieo",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
}
},
"employmentHistory": [
{
"asOfDate": "2020-07-31",
"employerName": "Amazing Community Pharmacy LLC",
"legalEntityID": {
"legalEntityID": "111111111"
},
"systemRefreshDate": "2021-08-01",
"employerAddress": {
"lineOne": "13 EMN T 1",
"lineTwo": null,
"lineThree": null,
"cityName": "CIEO",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
},
"employmentDetail": [
{
"effectiveDate": "2019-12-23",
"originalHireDate": "2015-08-10",
"workerStatusCode": {
"code": "A",
"name": "Active"
},
"workLevelCode": {
"code": "Full time",
"name": "Full time"
},
"positionTitle": null,
"positionStartDate": "2015-08-10",
"positionEndDate": null,
"positionTenureDuration": "P4Y10M12D",
"standardHours": 0.0
}
],
"remunerationSummary": [
21{
"payrollYear": 2020,
"baseRemunerationAmount": {
"amount": 30769.2,
"currencyCode": "USD"
},
"additionalRemunerations": [
{
"remunerationTypeCode": "YTD Bonus",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Overtime",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Others",
"remunerationAmount": {
"amount": 15206.85,
"currencyCode": "USD"
}
}
],
"totalAnnualRemunerationAmount": {
"amount": 45976.05,
"currencyCode": "USD"
},
"netPayYTDAmount": {
"amount": null,
"currencyCode": "USD"
}
}
]
},
{
"asOfDate": "2020-06-22",
"employerName": "Soul Cafe Llc",
"legalEntityID": {
"legalEntityID": "111111111"
},
"employerAddress": {
"lineOne": "13 EMN T 1",
"lineTwo": null,
"lineThree": null,
"cityName": "CIEO",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
},
"employmentDetail": [
{
"effectiveDate": "2015-08-18",
"originalHireDate": "2015-08-10",
"workerStatusCode": {
"code": "A",
"name": "Active"
},
"workLevelCode": {
"code": "Part time",
"name": "Part time"
},
"positionTitle": null,
"positionStartDate": "2015-08-10",
"positionEndDate": null,
"positionTenureDuration": "P4Y10M12D",
"standardHours": 60.0
}
],
"remunerationSummary": [
{
"payrollYear": 2019,
22"baseRemunerationAmount": {
"amount": 99999.9,
"currencyCode": "USD"
},
"additionalRemunerations": [
{
"remunerationTypeCode": "YTD Bonus",
"remunerationAmount": {
"amount": 39895.44,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Overtime",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Others",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
}
],
"totalAnnualRemunerationAmount": {
"amount": 139895.34,
"currencyCode": "USD"
},
"netPayYTDAmount": {
"amount": null,
"currencyCode": "USD"
}
},
{
"payrollYear": 2018,
"baseRemunerationAmount": {
"amount": 118692.28,
"currencyCode": "USD"
},
"additionalRemunerations": [
{
"remunerationTypeCode": "YTD Bonus",
"remunerationAmount": {
"amount": 26465.39,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Overtime",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Others",
"remunerationAmount": {
"amount": 1000.00,
"currencyCode": "USD"
}
}
],
"totalAnnualRemunerationAmount": {
"amount": 146157.67,
"currencyCode": "USD"
},
"netPayYTDAmount": {
"amount": null,
"currencyCode": "USD"
}
}
]
}
],
"historySummary": {
"availableHistorySourceCount": 2,
23"includedHistorySourceCount": 2
}
}
Criterias & Exceptions
If the supplied government ID and DOB do not match to an ADP record, a 404 person not found will be returned
Errors
404 Person not found
A person was not found from the supplied government ID
400 Invalid input
Invalid market vertical. Please provide a valid market vertical.
End consumer consent not provided
Invalid government ID format. Please check and try again.
Invalid date of birth format. Please provide in the format yyyy-mm-dd
Input
requestorInfo
marketSegmentCode (string) - the market vertical in which the request is applicable to. To be provided by development
contact (Required)
verifierName (string) - the company name of the verifier (ex. the name of the lender organization) (Required)
associateVerificationRequest
governmentID (string) - SSN (9 digit) (Required)
birthDate (string) - YYYY-MM-DD (Required)
associateConsentReceivedIndicator (Required)
responseFilters (Optional)
inactiveDays (string) - optional filter that returns only employees whose latest employment status is active (or leave) OR an
employment status of terminated but has a last pay date within 1) 90 days or 2) 30 days based on filter selection. To use filter, input
string value of either '90' or '30'. (Optional)
Sample Input
24{
"requestorInfo": {
"marketSegmentCode": "Prequal",
"verifierName": "Example Verifier Company"
},
"associateVerificationRequest": {
"governmentID": {
"id": "000000000"
},
"birthDate": "1984-01-01"
},
"associateConsentReceivedIndicator": true,
"responseFilters": {
"inactiveDays": "90"
}
}
Chapter 7
Employment & Income Verification (Detailed Basic)
Endpoint
POST https://api.adp.com/core/v1/associate-verifications/basic/employment-income
Summary
Obtains employment history, annual pay summary, and income history for the current year to date plus the last 2 full years. Includes payment
history at the pay period level, which can help assist in situations where a deeper look into income history is required.
Can be used for: mortgage, auto, tenant screening, personal loans, where income history is needed but deductions info is not necessary
Returns
asOfDate - last pay date (YYYY-MM-DD)
governmentID
id - ex. xxx-xx-0000
nameCode
code - i.e. SSN
name - i.e. Last 4 digits of SSN
personalData (most recent)
personName
givenName - first name
middleName - middle name
familyName - last name
address
lineOne
lineTwo
lineThree (if applicable)
cityName
subdivisionCode1
25name - i.e. CA
countryCode - i.e. US
postalCode - i.e. zip code
communication
telephones - phone number(s), if available
emails - email(s), if available
employmentHistory (for each employer)
employerName - employer name
legalEntityID - employer legal ID, i.e. federal employer ID number (FEIN)
systemRefreshDate - date of latest data refresh (YYYY-MM-DD)
employerAddress
lineOne
lineTwo
lineThree (if applicable)
cityName
subdivisionCode1
name - i.e. CA
countryCode - i.e. US
postalCode - i.e. zip code
originalHireDate - date which employee was hired
workerStatusCode - employee status (A - Active, T - Terminated, L - Leave)
code - A, T, L
name - Active, Terminated, Leave
workLevelCode - employment type (i.e. Full-time, part-time, regular, temp, contractor)
code - Full time, Part time. For employers that use ADP Payroll HCM such as WorkForce Now, they can enter a freeform text
to denote a worker level code for the employee, of which will be provided
name - Full time, Part time. For employers that use ADP Payroll HCM such as WorkForce Now, they can enter a freeform text
to denote a worker level name for the employee, of which will be provided
payrollGroupCode - payroll group code
code - payroll group code
positionTitle - job title
positionStartDate - most recent hire date
positionEndDate - termination date
positionTenureDuration - tenure (ISO 8601)
standardHours - hours entered in the Payroll system by the employer, most often this number is hours per week. For full time
employees, in general, it is usually 40 and for part time it will reflect the hours scheduled to work per week
remunerationSummary - YTD pay for the current year to date, plus last 2 full years. For the case when data is quarterly in nature (i.e.
data source only comes from tax data), then only the gross YTD will be available
payrollYear - year
baseRemunerationAmount - YTD Base
amount
currencyCode - i.e. USD
additionalRemunerations
remunerationTypeCode - YTD Bonus
amount
currencyCode - i.e. USD
remunerationTypeCode - YTD Overtime
amount
currencyCode - i.e. USD
remunerationTypeCode - YTD Others
amount
currencyCode - i.e. USD
totalAnnualRenumerationAmount - YTD Gross
amount
currencyCode - i.e. USD
netPayYTDAmount - YTD Net
amount
currencyCode - i.e. USD
paymentHistory (for each pay period)
26lastPayPeriodIndicator - true if this pay period is the last pay period of the year
quarterlyDataIndicator - indicates if this payment history detail comes from quarterly tax data, instead of payroll. When
quarterly data is provided, then the pay period will indicate the date ranges of the quarter (i.e. 1/1/20 - 3/31/20)
payDate - pay date
payPeriod
startDate - pay period begin date
endDate - pay period end date
payAmount
grossPayAmount - gross pay for this pay period
amount
currencyCode - i.e. USD
netPayAmount - net pay for this pay period
amount
currencyCode - i.e. USD
basePayAmount - base pay for this pay period
amount
currencyCode - i.e. USD
overtimePayAmount - overtime pay for this pay period
amount
currencyCode - i.e. USD
bonusPayAmount - bonus pay for this pay period
amount
currencyCode - i.e. USD
otherPayAmount - other pay (pay that is not categorized above, such as commission, car allowances, etc.) for this pay
period
amount
currencyCode - i.e. USD
payPeriodHours - total duration in hours for this pay period
remunerationBasisCode - pay description
name - Salary, Hourly, Daily
payCycleCode - pay frequency
code (corresponds to the name, respectively, as in M = Monthly, S = Semi-Monthly, etc.) - M, S, B, W, D, BO, BE, Q, SA,
A, 2, 4, 5
name - Monthly, Semi-Monthly, Bi-Weekly, Weekly, Daily, Bi-Weekly Odd, Bi-Weekly Even, Quarterly, Semi-Annual,
Annual, Every 2.6 wks, Every 4 wks, Every 5.2 wks
basePayRate - base/regular pay rate
amount
currencyCode - i.e. USD
payDistributions (for each distribution)
depositAmount - ex. the direct deposit amount
amount
currencyCode - i.e. USD
depositAccount
routingTransitID - routing number
accountNumber - direct deposit account number last 4, i.e. xxxxx-x0000
accountTypeCode - bank account type (Checking, Savings, Loan)
historySummary (this section provides some general information about the data returned)
availableHistorySourceCount - indicates the total number of employers which have information about the person
includedHistorySourceCount - indicates the number of employers whose data about the person was included in the response
availablePaymentHistoryMonths - denotes the number of months of paymentHistory for this person, categorized by the following:
payrollDataMonths - the number of months of paymentHistory data coming from payroll data (payroll data contains detailed
pay information by pay period)
quarterlyDataMonths - the number of months of payment data coming from quarterly tax data (although not as detailed as
payroll data, gross pay information is provided in quarters)
Sample Response
27{
"asOfDate": "2020-04-08",
"governmentID": {
"id": "xxx-xx-0000",
"nameCode": {
"code": "SSN",
"name": "Last 4 digits of SSN"
}
},
"personalData": {
"personName": {
"givenName": "First",
"middleName": "Middle",
"familyName": "Last"
},
"communication": {
"telephones": [
{
"formattedNumber": 3101111111
}
],
"emails": [
{
"emailUri": "sample.email@test.com"
}
],
"internetAddresses": []
},
"address": {
"lineOne": "16 lgl",
"lineTwo": "Ui ",
"lineThree": null,
"cityName": "Cieo",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
}
},
"employmentHistory": [
{
"employerName": "Amazing Community Pharmacy LLC",
"legalEntityID": {
"legalEntityID": "222222222"
},
"systemRefreshDate": "2020-04-09",
"employerAddress": {
"lineOne": "13 EMN T 1",
"lineTwo": null,
"lineThree": null,
"cityName": "CIEO",
"subdivisionCode1": {
"name": "IL"
},
"countryCode": "US",
"postalCode": "99999"
},
"originalHireDate": "2015-08-10",
"workerStatusCode": {
"code": "A",
"name": "Active"
},
"workLevelCode": {
"code": "Full time",
"name": "Full time"
},
"positionTitle": null,
"positionStartDate": "2015-08-10",
"positionEndDate": null,
"positionTenureDuration": "P4Y10M12D",
"standardHours": 0.0,
"remunerationSummary": [
{
"payrollYear": 2020,
"baseRemunerationAmount": {
"amount": 30769.2,
"currencyCode": "USD"
28},
"additionalRemunerations": [
{
"remunerationTypeCode": "YTD Bonus",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Overtime",
"remunerationAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
{
"remunerationTypeCode": "YTD Others",
"remunerationAmount": {
"amount": 15206.85,
"currencyCode": "USD"
}
}
],
"totalAnnualRemunerationAmount": {
"amount": 45976.05,
"currencyCode": "USD"
},
"netPayYTDAmount": {
"amount": null,
"currencyCode": "USD"
}
}
],
"paymentHistory": [
{
"lastPayPeriodIndicator": true,
"quarterlyDataIndicator": false,
"payDate": "2020-04-08",
"payPeriod": {
"startDate": "2020-03-23",
"endDate": "2020-04-05"
},
"payAmount": {
"grossPayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"netPayAmount": {
"amount": 2371.5,
"currencyCode": "USD"
},
"basePayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"overtimePayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"bonusPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"otherPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
"payPeriodHours": 60.0,
"payDistributions": [
{
"depositAmount": {
"amount": 2371.5,
"currencyCode": "USD"
},
"depositAccount": {
"routingTransitID": "11111111",
"accountNumber": "xxx-xx-0000",
29"accountTypeCode": "Checking"
}
}
]
},
{
"lastPayPeriodIndicator": false,
"quarterlyDataIndicator": false,
"payDate": "2020-03-25",
"payPeriod": {
"startDate": "2020-03-09",
"endDate": "2020-03-22"
},
"payAmount": {
"grossPayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"netPayAmount": {
"amount": 2371.51,
"currencyCode": "USD"
},
"basePayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"overtimePayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"bonusPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"otherPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
"payPeriodHours": 30.0,
"payDistributions": [
{
"depositAmount": {
"amount": 2371.51,
"currencyCode": "USD"
},
"depositAccount": {
"routingTransitID": "11111111",
"accountNumber": "xxx-xx-0000",
"accountTypeCode": "Checking"
}
}
]
},
{
"lastPayPeriodIndicator": false,
"quarterlyDataIndicator": false,
"payDate": "2020-03-11",
"payPeriod": {
"startDate": "2020-02-24",
"endDate": "2020-03-08"
},
"payAmount": {
"grossPayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"netPayAmount": {
"amount": 2371.52,
"currencyCode": "USD"
},
"basePayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"overtimePayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
30"bonusPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"otherPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
"payPeriodHours": 60.0,
"payDistributions": [
{
"depositAmount": {
"amount": 2371.52,
"currencyCode": "USD"
},
"depositAccount": {
"routingTransitID": "11111111",
"accountNumber": "xxx-xx-0000",
"accountTypeCode": "Checking"
}
}
]
},
{
"lastPayPeriodIndicator": false,
"quarterlyDataIndicator": false,
"payDate": "2020-02-26",
"payPeriod": {
"startDate": "2020-02-10",
"endDate": "2020-02-23"
},
"payAmount": {
"grossPayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"netPayAmount": {
"amount": 2371.51,
"currencyCode": "USD"
},
"basePayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"overtimePayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"bonusPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"otherPayAmount": {
"amount": 0.0,
"currencyCode": "USD"
}
},
"payPeriodHours": 60.0,
"payDistributions": [
{
"depositAmount": {
"amount": 2371.51,
"currencyCode": "USD"
},
"depositAccount": {
"routingTransitID": "11111111",
"accountNumber": "xxx-xx-0000",
"accountTypeCode": "Checking"
}
}
]
},
{
"lastPayPeriodIndicator": false,
"quarterlyDataIndicator": false,
"payDate": "2020-02-12",
"payPeriod": {
"startDate": "2020-01-27",
31"endDate": "2020-02-09"
},
"payAmount": {
"grossPayAmount": {
"amount": 19183.98,
"currencyCode": "USD"
},
"netPayAmount": {
"amount": 11825.72,
"currencyCode": "USD"
},
"basePayAmount": {
"amount": 3846.15,
"currencyCode": "USD"
},
"overtimePayAmount": {
"amount": 0.0,
"currencyCode": "USD"
},
"bonusPayAmount": {
"amount": 15206.85,
"currencyCode": "USD"
},
"otherPayAmount": {
"amount": 130.98,
"currencyCode": "USD"
}
},
"payPeriodHours": 60.0,
"payDistributions": [
{
"depositAmount": {
"amount": 11825.72,
"currencyCode": "USD"
},
"depositAccount": {
"routingTransitID": "11111111",
"accountNumber": "xxx-xx-0000",
"accountTypeCode": "Checking"
}
}
]
}
]
}
],
"historySummary": {
"availableHistorySourceCount": 2,
"includedHistorySourceCount": 2,
"availablePaymentHistoryMonths": {
"payrollDataMonthCount": 5,
"quarterlyDataMonthCount": 0
}
}
}
Criterias & Exceptions
If the supplied government ID and DOB do not match to an ADP record, a 404 person not found will be returned
Errors
404 Person not found
A person was not found from the supplied government ID
400 Invalid input
32You can also read
