Employer Payroll Identification

The Employer Payroll Identification API helps you identify where your users keep their direct deposits and who their payroll provider is.

The API serves two workflows:

• Workflow 1: Those who do not have a relationship with a switch partner. The API response will identify the paycheck transactions of your customers as well as their employer and payroll provider (where applicable).

• Workflow 2: Those who have a relationship with a switch partner (Atomic or Truv). Switch partners can use the API response to facilitate direct deposit switches to your bank.

The following depicts the differences between the workflows:

Requirements

The API will implement a 90-day look-back period for data retrieval and will operate on a rolling basis, determined by the requests sent to the API.

Responses from the API will be sorted based on the last_posted_date field, with the most recent entries appearing first and then descending in order of recency.

In cases where multiple paychecks have identical posted dates, their order in the response is not significant as long as they both appear as the most recent entries.

Access/Authentication

Accessing and authenticating is through the Platform API.

warning

Instead of using the accept header described in the “versioning” section, you will use application/vnd.mx.api.v2+json as the Accept header.

Once authenticated with the Platform API, you will be allowed to make successful calls to the Employer Payroll Identification API

URLs

Use the Production environment for testing.

Environment	Hostname
Production	api.mx.com

API Request Parameters

You will be required to provide a user_guid to initiate the request to the API. A switch_partner_id is optional (but recommended if you have a prior integration to a switch partner).

• user_guid: The unique identifier for the user. Required Field

• switch_partner_id: A unique identifier for the switch partner you’re integrated with. This request parameter will be defaulted to ‘null’. Optional Field Valid IDs are as follows: 

  1. SWP-3846 → atomic
  2. SWP-1337 → truv

cURL Request (without switch_partner_id)

Request

Response

Language:shell

_10

$ curl -L -X GET 'https://api.mx.com/users/:user_guid/identify_payrolls \

_10

-H 'Accept: application/vnd.mx.api.v2+json' \

_10

-H 'Authorization: Basic BASE_64_ENCODING_OF{client_external_guid:accessor_api_key}'

cURL Request (with switch_partner_id)

Request

Response

Language:shell

_10

$ curl -L -X GET 'https://api.mx.com/users/:user_guid/identify_payrolls?switch_partner_id=SWP-#### \

_10

-H 'Accept: application/vnd.mx.api.v2+json' \

_10

-H 'Authorization: Basic BASE_64_ENCODING_OF{client_external_guid:accessor_api_key}'

Appendix

Glossary

1. Switch Partner: A financial company that offers access to payroll, HRIS systems, and merchants and facilitates a range of financial services including direct deposit switching, income and employment verification, and payment method updating (i.e. Atomic, Truv).
2. Payroll Provider: Companies like ADP, Workday, Paylocity, etc. Payroll providers can also be employers.
3. Employer: Who a user works for. For example, a user may work for McDonald's and the employer may be McDonald’s OR the franchise owner. Employers can also be merchants.

Data Dictionary

Field	Value	Definition	Data Type
account	object	The object that will provide account level information related to the paycheck transactions of the user	dictionary
account_guid	parameter	The unique identifier for the account belonging to the user. Defined by MX. This will begin with ‘ACT’	string
name	parameter	The name of the account relating to the paycheck	string
nickname	parameter	The nickname of the account relating to the paycheck	string
type	parameter	The account type associated to the paycheck	string
paycheck_deposits	object	The object that will contain the transactions of the paycheck associated with the account	dictionary
guid	parameter	A unique id associated to the paycheck deposit. Defined by MX. This will begin with ‘PYT’	string
amount	parameter	The paycheck amount associated with the transaction	integer
description	parameter	The feed description of the paycheck transaction	string
switch_partner_name	parameter	The name of the switch partner you are integrated with. This field will be null if a switch_partner_id is not provided in the request body	string
employer_name	parameter	The identified employer associated with the paycheck transaction	string
paycheck_count	parameter	The paycheck count represents the number of times the paycheck was posted to the account in the last 90 days	integer
partner_employer_id	parameter	The employer ID, associated to the switch partner’s employer ID. This field will be null if a switch_partner_id is not provided in the request body	string
partner_payroll_id	parameter	The partner ID, associated to the switch partner’s payroll ID. This field will be null if a switch_partner_id is not provided in the request body	string
payroll_name	parameter	The identified payroll name associated to the paycheck transaction	string
transaction_guid	parameter	The unique MX generated ID for the transaction	string
last_posted_date	parameter	The last date of the paycheck. UTC Timecode Stamp	date (ISO 8601)
status	parameter	The status of the paycheck transaction. Possible values are pending, posted	string