Introduction

The Payroll API is a REST API allowing authorized clients to consume data that includes broker, lender, and deal information. Follow the application to completion by watching deal and compliance status updates.

Our project team will gladly work through a plan to get you connected to our Payroll API by setting up a development sandbox with access application data so that you can work independently on your solution. We will share our experiences and best practices to make this process as smooth as possible.

Authentication

POST https://api-link.newton.ca/payroll/token HTTP/1.1
Content-Type: application/json

Request

{
    "username" : "<username>",
    "password" : "<password>"
}

Response

{
    "token": "ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...", 
    "message": "Success"
}

Payroll API consumers must be authenticated and authorized to make API calls.

Payroll API uses JSON Web Tokens (JWTs) to authenticate requests. Successful authentication request will return an access token that is valid for 1 hour. All API calls must include an access token (bearer) in the Authorization header.

Consumers are encouraged to cache and reuse access tokens and only issue an authentication request before an API call if the token had expired or is about to expire.

Authorization

Payroll API access token's claims indicates which request methods can be performed and what data will be returned by the API.

An access token will contain one of the following claims:

https://claim.newton.ca/tenant - grants access to broker and deal data from specific tenants
https://claim.newton.ca/firm - grants access to broker and deal data from specific firms
https://claim.newton.ca/network - grants access to broker and deal data from specific networks

If https://claim.newton.ca/tenant claim is present in the token, for Broker and Deal operation requests with networkCode parameter, the network code will be ignored and only tenant specific data will be returned.

If https://claim.newton.ca/firm claim is present in the token, for Broker and Deal operation requests with networkCode parameter, the list of accessible firms will be narrowed down to those belonging to the requested network.

Definitions

GET https://api-link.newton.ca/payroll/v2/definitions
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...

Retrieves a list of enumerator definitions that are used in deal details. Some of these enumerators can also be used for filtering deals returned in Deals operation.

LenderID property returned by the Definitions operations is marked deprecated, meaning it will be removed in the future. Consumers should use Lender operation instead, to get a list of lenders, their codes and names.

Responses

Sample Response

200 Response

{
  "dealStatusID": {
    "1": "New",
    "2": "Submitted",
    "3": "Approved"
  },
  "mortgageStatusID": {
    "2": "In Progress",
    "3": "Submitted",
    "4": "Accepted",
    "5": "Declined",
    "6": "Approved"
  },
  "mortgagePositionID": {
    "1": "First",
    "2": "Second",
    "3": "Third"
  },
  "purposeID": {
    "0": "Purchase",
    "2": "Refinance",
    "3": "ETO"
  }
}

Status	Schema
200 OK	Definitions

Definitions

Name	Type	Description
lenderID deprecated	object nullable	List of lenders (key-value pairs)
dealStatusID	object nullable	List of deal statuses (key-value pairs)
mortgageStatusID	object nullable	List of mortgage statuses (key-value pairs)
mortgagePositionID	object nullable	List of mortgage positions (key-value pairs)
purposeID	object nullable	List of mortgage purposes (key-value pairs)
paymentFrequencyID	object nullable	List of payment frequencies (key-value pairs)
rateTypeID	object nullable	List of rate types (key-value pairs)
mortgageTypeID	object nullable	List of mortgage types (key-value pairs)
streetTypeID	object nullable	List of street types (key-value pairs)
importStatusID	object nullable	List of import statuses (key-value pairs)
filterModeID	object nullable	List of filter modes (key-value pairs)
complianceStatusID	object nullable	List of compliance statuses (key-value pairs)
posSystemID	object nullable	List of PoS systems (key-value pairs)

Lender

GET https://api-link.newton.ca/payroll/v2/lenders
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...

Get a list of lenders, their codes and names. This list changes often and should be consumed for updates on a regular basis.

Responses

Sample Response

200 Response

[
  {
    "code": 1654,
    "name": "Canadian Mortgages Inc"
  },
  {
    "code": 1972,
    "name": "Equitable Bank"
  },
  {
    "code": 1269,
    "name": "First National Financial"
  },
  {
    "code": 1054,
    "name": "Fisgard Asset Management"
  },
  {
    "code": 1479,
    "name": "Haventree Bank"
  },
  {
    "code": 1279,
    "name": "Home Trust"
  },
  {
    "code": 1387,
    "name": "Manulife Bank"
  },
  {
    "code": 1978,
    "name": "MCAP Mortgage Corporation"
  },
  {
    "code": 1499,
    "name": "Scotiabank / Banque Scotia"
  },
  {
    "code": 1237,
    "name": "TD Mortgage Services"
  }
]

Status	Schema
200 OK	array(Lender)

Lender

Name	Type	Description
code	integer(int32)	Lender code
name	string nullable	Lender name

Brokers

GET https://api-link.newton.ca/payroll/v2/brokers
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...

GET https://api-link.newton.ca/payroll/v2/{networkcode}/brokers
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...

Retrieve a list of the brokers/agents and their details. This list changes often and should be consumed for updates on a regular basis.

Parameters

Name	In	Type	Description
networkCode	path	string	Brokerage network code

Responses

Sample Response

200 Response

[
  {
    "agentID": "af269125-2abd-42b1-86b4-647130e6ac94",
    "expertUsername": "JSMITH",
    "expertProfileId": "36453",
    "firmCode": "ABCD",
    "name": "John Smith",
    "username": "john.smith",
    "linkId": "jsmith100",
    "licenseeId": "ABCD0001",
    "shortCode": "i2otUV45QTht",
    "publicURL": "https://<client-journey-url>/sso/public.php?sc=i2otUV45QTht"
  },
  {
    "agentID": "92200fa3-3f39-46a7-bdc4-b22490c34a78",
    "expertUsername": "RBERRY",
    "expertProfileId": "1673",
    "firmCode": "ABCD",
    "name": "Robert Berry",
    "username": "robert.berry",
    "linkId": "rberry100",
    "licenseeId": "ABCD0001",
    "shortCode": "o1Cr6OgJ9L1X",
    "publicURL": "https://<client-journey-url>/sso/public.php?sc=o1Cr6OgJ9L1X"
  },
  {
    "agentID": "cf609321-cf27-4233-80ea-33f31a97602b",
    "expertUsername": "DBROWN",
    "expertProfileId": "38363",
    "firmCode": "ABCD",
    "name": "David Brown",
    "username": "david.brown",
    "linkId": "dbrown100",
    "licenseeId": "ABCD0001",
    "shortCode": "Q5KleYLCm135",
    "publicURL": "https://<client-journey-url>/sso/public.php?sc=Q5KleYLCm135"
  }
]

Status	Schema
200 OK	array(Agent)

Agent

Name	Type	Description
agentID	string(uuid)	Unique agent identifier
expertUsername	string nullable	Agent's username as appears in Expert
expertProfileId	string nullable	Agent's Expert profile Id
firmCode	string nullable	Agent's firm code
name	string nullable	Agent's full name
username	string nullable	Agent's username
linkId	string nullable	Agent's Link ID
licenseeId	string nullable	Agent's tenant code (licenseeId)
removedDateTimeUTC	string(date-time) nullable	Timestamp when agent was removed
shortCode	string nullable	Agent's short code
publicURL	string nullable	Client Journey URL

Deal

GET https://api-link.newton.ca/payroll/v2/deals
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...

GET https://api-link.newton.ca/payroll/v2/{networkcode}/deals
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...

Filter and retrieve deal information required for payroll processing that includes borrower, subject property, mortgage, lender and compliance statuses.

Parameters

Name	In	Type	Description
networkCode	path	string	Brokerage network code
hoursBack	query	integer(int32)	Hours back
loanCode	query	string	Loan code
expertLoanCode	query	string	Expert loan code
posSystemId	query	integer(int32)	PoS system
firmCode	query	string	Firm code
licenseeId	query	string	Tenant code
officeName	query	string	Office name
username	query	string	Username
expertUsername	query	string	Expert username
closingDateFrom	query	string(date-time)	Earliest closing date
closingDateTo	query	string(date-time)	Latest closing date
limitTotalResults	query	integer(int32)	Maximum number of results
lenderId	query	integer(int32)	Lender code
lenderName	query	string	Lender name
clientFirstName	query	string	Applicant's first name
clientLastName	query	string	Applicant's last name
coClientFirstName	query	string	Co-applicant's first name
coClientLastName	query	string	Co-applicant's last name
hasCreditBureau	query	boolean	With credit bureau?
cb deprecated	query	boolean	With credit bureau?
lenderReferenceNumber	query	string	Lender reference number (Application number)
dealStatusID	query	integer(int32)	Status
importStatusID	query	string	Import status
filterMode	query	FilterMode	Filter mode

Responses

Sample Response

200 Response

[
  {
    "posSystemId": 40,
    "brokerNetwork": "DLC",
    "firmCode": "ABCD",
    "licenseeId": "ABCD0001",
    "officeName": "Mortgage Financial Partners",
    "organizationName": "Mortgage Financial Partners",
    "expertProfileId": "36453",
    "username": "john.smith",
    "linkId": "jsmith100",
    "agentName": "John Smith",
    "agentID": "af269125-2abd-42b1-86b4-647130e6ac94",
    "loanCode": "VDLC-41203",
    "applicationDate": "2023-07-31T18:32:18",
    "dateUpdated": "2023-07-31T11:43:35",
    "dealStatusID": 1,
    "clientFirstName": "Brooke",
    "clientLastName": "Drummond",
    "clientDOB": "1987-07-27",
    "clientPhone": "6405559898",
    "clientEmail": "brooke.drummond@example.com",
    "streetNumber": "8899",
    "streetName": "Birnam",
    "streetType": "Drive",
    "streetTypeID": 9,
    "city": "Ilderton",
    "province": "Ontario",
    "postalCode": "N0K1B0",
    "mortgagePositionID": 1,
    "lenderID": "1499",
    "lenderName": "Scotiabank / Banque Scotia",
    "fundedAmount": 648000,
    "mortgageRate": 0,
    "mortgageAmortization": 25,
    "closingDate": "2023-12-14",
    "maturityDate": "2023-12-14",
    "purposeID": 0,
    "paymentFrequencyID": 3,
    "private": false,
    "fixed": false,
    "isCommercialDeal": false,
    "firstTimeBuyer": true,
    "readyForCompliance": false,
    "complianceConfirmed": false,
    "complianceStatusID": 0
  },
  {
    "posSystemId": 40,
    "brokerNetwork": "DLC",
    "firmCode": "ABCD",
    "licenseeId": "ABCD0001",
    "officeName": "Mortgage Financial Partners",
    "organizationName": "Mortgage Financial Partners",
    "expertProfileId": "1673",
    "username": "robert.berry",
    "linkId": "rberry100",
    "agentName": "Robert Berry",
    "agentID": "92200fa3-3f39-46a7-bdc4-b22490c34a78",
    "loanCode": "VOHFP-54623",
    "submissionReferenceNumber": "M101319878",
    "lenderReferenceNumber": "OHFP.0002619",
    "applicationDate": "2022-02-09T17:39:55",
    "dateUpdated": "2023-09-11T12:21:43",
    "creditBureau": "TransUnion",
    "dealStatusID": 2,
    "mortgageStatusID": 2,
    "clientFirstName": "Luis",
    "clientLastName": "Diaz",
    "clientDOB": "1982-02-02",
    "clientPhone": "9556565655",
    "clientEmail": "luis.diaz@example.com",
    "streetNumber": "34",
    "unitNumber": "23",
    "streetName": "Hollywood",
    "streetType": "Carrefour",
    "streetDirection": "S",
    "city": "Toronto",
    "province": "Ontario",
    "postalCode": "M2N0A9",
    "mortgagePositionID": 1,
    "lenderID": "1499",
    "lenderName": "Scotiabank / Banque Scotia",
    "fundedAmount": 640000,
    "mortgageRate": 3,
    "mortgageAmortization": 25,
    "closingDate": "2023-09-13",
    "maturityDate": "2028-09-13",
    "purposeID": 0,
    "paymentFrequencyID": 3,
    "private": false,
    "rateTypeID": 0,
    "fixed": true,
    "mortgageTerm": 60,
    "isCommercialDeal": false,
    "firstTimeBuyer": true,
    "readyForCompliance": false,
    "complianceConfirmed": false,
    "complianceStatusID": 0
  }
]

Status	Schema
200 OK	array(Deal)

Deal

Name	Type	Description
posSystemId	integer(int32)	PoS system
brokerNetwork	string nullable	Broker network
firmCode	string nullable	Firm code
licenseeId	string nullable	Agent tenant code (Licensee Id)
officeName	string nullable	Agent office name
organizationName	string nullable	Firm name (organization)
expertUsername	string nullable	Agent's expert username
expertProfileId	string nullable	Agent's Expert profile Id
username	string nullable	Agent's username
linkId	string nullable	Agent's Link ID
agentName	string nullable	Agent name
agentID	string(uuid) nullable	Unique agent identifier
loanCode	string nullable	Loan code
expertLoanCode	string nullable	Expert loan code
submissionReferenceNumber	string nullable	Submission reference number (Application number)
lenderReferenceNumber	string nullable	Lender reference number (Broker reference number)
applicationDate	string(date-time)	Application date
dateUpdated	string(date-time) nullable	Application update date
lenderPaymentReceived	string(date-time) nullable	Lender payment received date
creditBureau	string nullable	Credit bureau provider
dealStatusID	integer(int32) nullable	Deal status
importStatusID	integer(int32) nullable	Import status
mortgageStatusID	integer(int32) nullable	Mortgage status
clientFirstName	string nullable	Client first name
clientLastName	string nullable	Client last name
clientDOB	string(date) nullable	Client date of birth
clientPhone	string nullable	Client phone number
clientEmail	string nullable	Client email address
coClientFirstName	string nullable	Co-client first name
coClientLastName	string nullable	Co-client last name
coClientDOB	string(date) nullable	Co-client date of birth
coClientPhone	string nullable	Co-client phone number
coClientEmail	string nullable	Co-client email address
streetNumber	string nullable	Subject property address street number
unitNumber	string nullable	Subject property address unit number
streetName	string nullable	Subject property address street name
streetType	string nullable	Subject property address street type
streetTypeID deprecated	StreetType nullable
streetDirection	string nullable	Subject property address street direction
city	string nullable	Subject property address city
province	string nullable	Subject property address province
postalCode	string nullable	Subject property address postal code
mortgagePositionID	integer(int32) nullable	Mortgage position
lenderID	string nullable	Lender code
lenderName	string nullable	Lender name
fundedAmount	number(double) nullable	Funded amount
mortgageRate	number(double) nullable	Mortgage rate
mortgageAmortization	integer(int32) nullable	Mortgage amortization
closingDate	string(date) nullable	Closing date
maturityDate	string(date) nullable	Maturity date
purposeID	integer(int32) nullable	Mortgage purpose
paymentFrequencyID	integer(int32) nullable	Payment frequency
mortgageType	integer(int32) nullable	Mortgage type
private	boolean nullable	Private mortgage
rateTypeID	integer(int32) nullable	Rate type
fixed	boolean nullable	Fixed rate
mortgageTerm	integer(int32) nullable	Mortgage term
isCommercialDeal	boolean nullable	Is commercial deal?
firstTimeBuyer	boolean nullable	First-time home buyer
agentRemovedDateTimeUTC	string(date-time) nullable	Agent removed timestamp (UTC)
readyForCompliance	boolean nullable	Ready for compliance
complianceConfirmed	boolean nullable	Compliance confirmed
complianceStatusID	integer(int32) nullable	Compliance status
complianceStatusUpdateDateTimeUTC	string(date-time) nullable	Compliance status update timestamp (UTC)

Enumerations

FilterMode

Values	Description
0	Submittable
1	Not Imported
2	All

StreetType

Values	Description
1	Avenue
2	Boulevard
3	Circle
4	Crescent
5	Drive
6	Gate
7	Highway
8	Lane
9	Line
10	Road
11	Route
12	Street
13	Terrace
14	Trail
15	Way
16	Common
17	Court
18	Green
19	Manor
20	Place
21	Rise
22	Landing
23	Bay
24	Close
25	Link
26	Mews
27	View
28	Quay
29	Square
30	Abbey
31	Acres
32	Alley
33	Autoroute
34	Beach
35	Bend
36	By Pass
37	Byway
38	Campus
39	Cape
40	Centre
41	Chase
42	Circuit
43	Concession
44	Corners
45	Crossing
46	Culde Sac
47	Cove
48	Dale
49	Dell
50	Diversion
51	Downs
52	End
53	Estates
54	Expressway
55	Extension
56	Farm
57	Field
58	Forest
59	Freeway
60	Front
61	Gardens
62	Glade
63	Glen
64	Grounds
65	Grove
66	Harbour
67	Heights
68	Highlands
69	Hill
70	Hollow
71	Impasse
72	Island
73	Key
74	Knoll
75	Limits
76	Lookout
77	Loop
78	Mall
79	Maze
80	Meadow
81	Moor
82	Mount
83	Mountain
84	Orchard
85	Parade
86	Park
87	Parkway
88	Passage
89	Path
90	Pathway
91	Pines
92	Plaza
93	Point
94	Port
95	Private
96	Promenade
97	Range
98	Ridge
99	Row
100	Run
101	Subdivision
102	Thicket
103	Towers
104	Townline
105	Turnabout
106	Vale
107	Village
108	Vista
109	Walk
110	Wharf
111	Wood
112	Heath
113	Inlet
114	Plateau
115	Ramp
116	Villas
117	Wynd
315	Meadows