Introduction
Thanks for your interest in the Gig Wage API. We look forward to seeing what you build!
Requests and responses
Payloads for POST
, PUT
and PATCH
requests are expected to be JSON. Responses are JSON.
The base URL for the API depends on the environment:
- Sandbox:
https://sandbox.gigwage.com/api/v1
- Production:
https://www.gigwage.com/api/v1
Sandbox Onboarding
Once you've been granted API access you'll need to onboard your business in the sandbox with valid test values. Some form fields accept arbitrary values, but the following fields need values that follow their sandbox rules, for successful integrations with our sandbox partners:
Screen | Field | Rule |
---|---|---|
Onboarding | First Name | Must be 2 or more alpha characters |
Onboarding | Last Name | Must be 2 or more alpha characters |
Onboarding | Date of Birth | Must put you at 18 years of age or older |
Onboarding | Phone Number | Must have the form of a valid phone number (easiest solution is to use your real one) |
Onboarding | Social Security Number | Must be 9 digits, the last 4 of which are 2222 |
Onboarding | Business Name | Must be 2 or more alpha characters |
Onboarding | EIN | Must be 9 digits, the last 4 of which are 2222 |
Onboarding | Address | 1 Market Street San Francisco, CA 94105 |
Bank Account Authorization | Username | Use user_good |
Bank Account Authorization | Password | Use pass_good |
Authentication
Authenticating against the API requires 3 request headers:
API key
The X-Gw-Api-Key
request header contains the "key" portion of the API key pair issued to your business.
request.headers['X-Gw-Api-Key'] = api_key
Timestamp
The X-Gw-Timestamp
request header contains the UNIX epoch (UTC) in milliseconds. Some implementations of strftime
provide this as %Q
. In Ruby for example:
timestamp = DateTime.now.strftime('%Q')
request.headers['X-Gw-Timestamp'] = timestamp
var timestamp = (new Date).getTime().toString();
If this is unavailable in your language or framework, multiplying the epoch by 1000 will be adequate.
Signature
The X-Gw-Signature
request header contains a SHA256 HMAC signature of the X-Gw-Timestamp
,
request method, endpoint and payload as json headers, using your secret key, in hex format.
timestamp = DateTime.now.strftime('%Q')
method = 'POST'
endpoint = '/api/v1/contractors'
payload = {
contractor: {
first_name: 'Karen',
last_name: 'Example',
email: 'karen@example.com',
}
}
data = [ timestamp, method, endpoint, payload ].join
signature = OpenSSL::HMAC.hexdigest("SHA256", api_secret, data)
request.headers['X-Gw-Signature'] = signature
var CryptoJS = require("crypto-js");
var timestamp = (new Date).getTime().toString();
var method = 'POST';
var endpoint = '/api/v1/contractors';
var payload = JSON.stringify({
"contractor": {
"first_name": 'Karen',
"last_name": 'Example',
"email": 'karen@example.com',
}
});
var data = [ timestamp, method, endpoint, payload ].join('');
var bytes = CryptoJS.HmacSHA256(data, api_secret);
var signature = bytes.toString(CryptoJS.enc.Hex);
Using CryptoJS
Authentication Summary
Every authenticated request, then, will contain these headers:
request.headers['X-Gw-Api-Key'] = api_key
request.headers['X-Gw-Timestamp'] = timestamp
request.headers['X-Gw-Signature'] = signature
var headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"X-Gw-Api-Key": api_key,
"X-Gw-Timestamp": timestamp,
"X-Gw-Signature": signature
}
The API will respond with an authentication error if:
- The API key is missing, invalid, revoked, or not associated with the secret key used to generate the signature
- The timestamp header is missing, invalid, or not within 60 seconds of the server's clock
- The signature header is anything but the correct signature for the supplied timestamp, request method, endpoint and payload using the secret key associated with the provided API key
Endpoints
Contractors
GET /api/v1/contractors/{id}
Returns the details for a given contractor
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
full | set 1 to return full information of contractor (including Address, phone number, and birthday) |
include_ssn | set 1 to return security number of contractor |
client.get("/api/v1/contractors/1004")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"contractor": {
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": true,
"has_debit": false,
"invited_at": "2021-05-03T22:18:16.965Z",
"invitation_accepted_at": "2021-06-03T22:18:16.965Z",
"created_at": "2021-05-03T22:18:16.965Z"
}
}
GET /api/v1/contractors
Parameters
All parameters are optional and should be passed as a query string on the URL:
Parameter | Description |
---|---|
size | The number of records to return. Default is 200, max is 200. |
page | For paginated results, the page number to return. For example, ?size=100&page=2 will return contractors 101-200. |
q | Search email, contractor's name or vendor's business name. Email is an exact match, and a partial match for the others. |
client.get("/api/v1/contractors?size=1&page=1")
fetch("https://sandbox.gigwage.com/api/v1/contractors", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"contractors": [
{
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": true,
"has_debit": false,
"invited_at": "2021-05-03T22:18:16.965Z",
"invitation_accepted_at": "2021-06-03T22:18:16.965Z",
"created_at": "2021-05-03T22:18:16.965Z"
}
]
}
GET /api/v1/contractors/find_by
Find a contractor by email, external_id or id
client.get("/api/v1/contractors/find_by?email=karen@example.com")
fetch("https://sandbox.gigwage.com/api/v1/contractors/find_by?email=karen@example.com", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"contractor": {
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"external_id": "",
"has_ach": true,
"has_debit": false,
"invited_at": "2021-05-03T22:18:16.965Z",
"invitation_accepted_at": "2021-06-03T22:18:16.965Z",
"created_at": "2021-05-03T22:18:16.965Z"
}
}
POST /api/v1/contractors
Creates a new contractor.
Parameters
Parameter | Description |
---|---|
contractor | The root of the payload (required) |
first_name | The contractor's first name (string, required) |
last_name | The contractor's last name (string, required) |
The contractor's email (string, required) |
client.post("/api/v1/contractors", {
contractor: {
first_name: "Karen",
last_name: "Example",
email: "karen@example.com"
}
})
fetch("https://sandbox.gigwage.com/api/v1/contractors", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"contractor": {
"first_name": "Karen",
"last_name": "Example",
"email": "karen@example.com"
}
})
})
Example JSON response
{
"contractors": [
{
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": false,
"has_debit": false,
"invited_at": null,
"invitation_accepted_at": null,
"created_at": "2021-05-03T22:18:16.965Z"
}
]
}
DELETE /api/v1/contractors/:id
Delete contractor record.
Note: You can only destroy new contractors that aren't associated with other businesses, and that have no payments or 1099s
client.delete("/api/v1/contractors/1004")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"contractors": [
{
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": false,
"has_debit": false,
"invited_at": null,
"invitation_accepted_at": null,
"created_at": "2021-05-03T22:18:16.965Z"
}
]
}
POST /api/v1/contractors/{id}/kyc
Submit KYC information for a contractor
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
contractor | The root of the payload (required) |
social_security | Contractor's social security number. For example: 123-12-1234 (string, required) |
phone_number | Contractor's phone number. Example: 123-123-1234 or 1231231234 (string, required) |
birthdate | Contractor's birthdate. Format: MM/DD/YYYY (date, required) |
vendor | If set, it means the contractor is a vendor and the request will require aditional information (see below) |
business_name | Vendor business name (string, required for vendors, ignored otherwise) |
ein | Vendor's EIN (string, required for vendors, ignored otherwise) |
business_formed_on | Date the vendor's business was formed (date, required for vendors, ignored otherwise) |
industry | Vendor's industry (string, required for vendors, ignored otherwise) |
entity | Vendor's entity (string, required for vendors, ignored otherwise) |
address1 | Contractor's address line 1 |
address2 | address line 2 |
city | City |
zip | Zip code |
state | State, 2 characters US State Code (ISO 3166-2) |
client.post("/api/v1/contractors/1004/kyc", {
contractor: {
social_security: "123-12-1234",
phone_number: "123-123-1234",
birthdate: "1/1/1981",
address1: "28201 E. Bonanza St.",
city: "South Park",
zip: "80440",
state: "CO"
}
})
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/kyc", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"contractor": {
"social_security": "123-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO"
}
})
})
Example JSON response
{
"contractor": {
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": false,
"has_debit": false,
"invited_at": null,
"invitation_accepted_at": null,
"created_at": "2021-05-03T22:18:16.965Z"
}
}
POST /api/v1/contractors/{id}/w9
Submit W9 information for a contractor you only want to create a 1099 for. This will also trigger an instant TIN check for the contractor. This contractor won't be able to accept payments, if you need them to receive payments use the kyc endpoint
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
contractor | The root of the payload (required) |
social_security | Contractor's social security number. For example: 123-12-1234 (string, required unless it's a vendor) |
phone_number | Contractor's phone number. Example: 123-123-1234 or 1231231234 (string, normally required) |
birthdate | Contractor's birthdate. Format: MM/DD/YYYY (date, normally required) |
tax_classification | Contractor's tax classification (string, required) |
llc_classification | LLC classification (C S P, required if tax_classification is limited_liability_corporation) |
other_classification | Contractor's tax classification if other is selected (string, optional) |
exempt_payee_code | Contractor's exempt payee code. See IRS Line 4, Exemptions for more details (integer 1-13, optional) |
fatca_reporting_exemption_code | Contractor's FATCA exempt code. See IRS Line 4, Exemptions for more details (string A-M, optional) |
vendor | If set, it means the contractor is a vendor and the request will require aditional information (see below) |
ein | Vendor's EIN (string, required for vendors, ignored otherwise) |
business_name | Vendor business name (string, required for vendors, ignored otherwise) |
dba | Vendor DBA if applicable (optional) |
address1 | Contractor's address line 1 |
address2 | address line 2 |
city | City |
zip | Zip code |
state | State, 2 characters US State Code (ISO 3166-2) |
paper_1099 | Send contractor a paper 1099 (boolean, optional, false by default) |
client.post("/api/v1/contractors/1004/w9", {
contractor: {
social_security: "123-12-1234",
phone_number: "123-123-1234",
birthdate: "1/1/1981",
tax_classification: "c_corporation",
address1: "28201 E. Bonanza St.",
city: "South Park",
zip: "80440",
state: "CO"
}
})
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/w9", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"contractor": {
"social_security": "123-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"tax_classification": "c_corporation",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO"
}
})
})
Example JSON response
"contractor": {
"first_name": "Karen",
"last_name": "Example",
"email": "karen@example.com",
"social_security": "123-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"tax_classification": "c_corporation",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO",
"llc_classification": null,
"other_classification": null,
"business_name": null,
"dba": null,
"ein": null,
"exempt_payee_code": null,
"fatca_reporting_exemption_code": null
"tin_check_status": "failure",
"tin_check_reason": "TIN entered is not currently issued.",
"paper_1099": false
}
PATCH /api/v1/contractors/{id}/w9
Update W9 information for a contractor.
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
contractor | The root of the payload (required) |
social_security | Contractor's social security number. For example: 123-12-1234 (string, required unless it's a vendor) |
phone_number | Contractor's phone number. Example: 123-123-1234 or 1231231234 (string, normally required) |
birthdate | Contractor's birthdate. Format: MM/DD/YYYY (date, normally required) |
tax_classification | Contractor's tax classification (string, required) |
llc_classification | LLC classification (C S P, required if tax_classification is limited_liability_corporation) |
other_classification | Contractor's tax classification if other is selected (string, optional) |
exempt_payee_code | Contractor's exempt payee code. See IRS Line 4, Exemptions for more details (integer 1-13, optional) |
fatca_reporting_exemption_code | Contractor's FATCA exempt code. See IRS Line 4, Exemptions for more details (string A-M, optional) |
vendor | If set, it means the contractor is a vendor and the request will require aditional information (see below) |
ein | Vendor's EIN (string, required for vendors, ignored otherwise) |
business_name | Vendor business name (string, required for vendors, ignored otherwise) |
dba | Vendor DBA if applicable (optional) |
address1 | Contractor's address line 1 |
address2 | address line 2 |
city | City |
zip | Zip code |
state | State, 2 characters US State Code (ISO 3166-2) |
paper_1099 | Send contractor a paper 1099 (boolean, optional, false by default) |
client.patch("/api/v1/contractors/1004/w9", {
contractor: {
social_security: "978-12-1234",
phone_number: "123-123-1234",
birthdate: "1/1/1981",
tax_classification: "c_corporation",
address1: "28201 E. Bonanza St.",
city: "South Park",
zip: "80440",
state: "CO"
}
})
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/w9", {
"method": "PATCH",
"headers": headers,
"body": JSON.stringify({
"contractor": {
"social_security": "978-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"tax_classification": "c_corporation",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO"
}
})
})
Example JSON response
"contractor": {
"first_name": "Karen",
"last_name": "Example",
"email": "karen@example.com",
"social_security": "978-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"tax_classification": "c_corporation",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO"
"llc_classification": null,
"other_classification": null,
"business_name": null,
"dba": null,
"ein": null,
"exempt_payee_code": null,
"fatca_reporting_exemption_code": null
"tin_check_status": "failure",
"tin_check_reason": "TIN entered is not currently issued.",
"paper_1099": false
}
GET /api/v1/contractors/{id}/w9
Get W9 information for a contractor
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
include_ssn | set 1 to return security number of contractor |
client.get("/api/v1/contractors/1004/w9")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/w9", {
"method": "GET",
"headers": headers
})
Example JSON response
"contractor": {
"first_name": "Karen",
"last_name": "Example",
"email": "karen@example.com",
"social_security": "123-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"tax_classification": "c_corporation",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO",
"llc_classification": null,
"other_classification": null,
"business_name": null,
"dba": null,
"ein": null,
"exempt_payee_code": null,
"fatca_reporting_exemption_code": null,
"tin_check_status": "failure",
"tin_check_reason": "TIN entered is not currently issued.",
"paper_1099": false
}
PATCH /api/v1/contractors/{id}
Updates an existing contractor. If the contractor has already registered, changes to the email address will not affect email delivery: emails will be delivered to the address managed by the contractor. Any supported attributes not supplied in the request will not be changed.
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
contractor | The root of the payload (required) |
first_name | The contractor's first name (string, optional) |
last_name | The contractor's last name (string, optional) |
The contractor's email (string, optional) | |
social_security | Contractor's social security number. For example: 123-12-1234 |
phone_number | Contractor's phone number. Required if address exists. Example: 123-123-1234 or 1231231234 |
birthdate | Contractor's birthdate. Format: MM/DD/YYYY |
address1 | Contractor's address line 1 |
address2 | address line 2 |
city | City |
zip | Zip code |
state | State, 2 characters US State Code (ISO 3166-2) |
client.patch("/api/v1/contractors/1004", {
contractor: {
email: "karene2@example.com"
}
})
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004", {
"method": "PATCH",
"headers": headers,
"body": JSON.stringify({
"contractor": {
"email": "karene2@example.com"
}
})
})
Example JSON response
{
"contractor": {
"id": 1004,
"email": "karene2@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": false,
"has_debit": false,
"invited_at": null,
"invitation_accepted_at": null,
"created_at": "2021-05-03T22:18:16.965Z"
}
}
GET /api/v1/contractors/{id}/1099s
Get contractor 1099s
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
client.get("/api/v1/contractors/1004/1099s")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/1099s", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"1099s""": [{
"id": 1,
"contractor_id": 1004,
"year": 2021,
"status": "draft",
"type": "Nec",
"validation_errors": null,
"box1": 2500.0,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}]
}
POST /api/v1/contractors/{id}/invite
Delivers a secure onboarding email invitation to an existing contractor who has never been paid. If the contractor has an outstanding unaccepted invitation, the old invitation will be invalidated.
Parameters
No parameters are required or accepted
client.post("/api/v1/contractors/1004/invite")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/invite", {
"method": "POST",
"headers": headers
})
Example JSON response
{
"contractor": {
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"has_ach": true,
"has_debit": false,
"invited_at": "2021-05-03T22:18:16.965Z",
"invitation_accepted_at": "2021-06-03T22:18:16.965Z",
"created_at": "2021-05-03T22:18:16.965Z"
}
}
POST /api/v1/contractors/{id}/invitations
Creates an invitation for the contractor, but doesn't deliver the email If the contractor has an outstanding unaccepted invitation, the old invitation will be invalidated.
Parameters
No parameters are required or accepted
client.post("/api/v1/contractors/1004/invitations")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/invitations", {
"method": "POST",
"headers": headers
})
Example JSON response
{
"invitation": {
"id": 1004,
"email": "karen@example.com",
"first_name": "Karen",
"last_name": "Example",
"token": "CsjhxAszesmhusHfyfHx",
"url": "https://sandbox.gigwage.com/users/invitation/accept?invitation_token=CsjhxAszesmhusHfyfHx",
"created_at": "2021-05-03T22:18:16.965Z"
}
}
POST /api/v1/contractors/{id}/identity_document
Submit a copy of a contractors identity document
Parameters
Parameter | Description |
---|---|
identity_document | The root of the payload (required) |
subtype | Type of document, driver_license or passport (string, required) |
front | Image of front of document |
back | Image of back of document |
client.post("contractors/1004/identity_document", {
identity_document: {
subtype: "passport",
front: File.new("front.jpg", "rb"),
back: File.new("back.jpg", "rb"),
},
multipart: true
})
Example JSON response
{
"identity_document": {
"id": 1,
"subtype": "passport",
"created_at": "2021-03-18T00:32:39.652Z",
"updated_at": "2021-03-18T00:32:39.652Z"
}
}
POST /api/v1/contractors/{id}/tin_check
Request a TIN check for a contractor.
Note: TIN checks are automatically run on POST and PATCH W9 endpoints
client.post("contractors/1004/tin_check")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1004/tin_checks", {
"method": "POST",
"headers": headers
})
Example JSON response
"contractor": {
"first_name": "Karen",
"last_name": "Example",
"email": "karen@example.com",
"social_security": "123-12-1234",
"phone_number": "123-123-1234",
"birthdate": "1/1/1981",
"tax_classification": "c_corporation",
"address1": "28201 E. Bonanza St.",
"city": "South Park",
"zip": "80440",
"state": "CO",
"llc_classification": null,
"other_classification": null,
"business_name": null,
"dba": null,
"ein": null,
"exempt_payee_code": null,
"fatca_reporting_exemption_code": null
"tin_check_status": "failure",
"tin_check_reason": "TIN entered is not currently issued.",
"paper_1099": false
}
Bank Accounts
GET /api/v1/contractors/{id}/accounts
Get all accounts for the contractor
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the contractor |
client.get("/api/v1/contractors/1234/accounts")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1234/accounts", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"accounts": [
{
"id": 2931,
"routing_number": "021000021",
"name": "Test Bank Account",
"account_type": "checking",
"last4": "6789",
"created_at": "2021-02-28T21:11:39.148Z",
"deactivated_at": null
}
]
}
POST /api/v1/contractors/{id}/accounts
Add a bank account to an existing contractor
Parameters
Parameter | Description |
---|---|
account | The root of the payload (required) |
account_number | Contractor's bank account number (string, required) |
routing_number | Bank's routing number (string, required) |
name | Bank account's nickname (string, required) |
account_type | Account type, checking or savings (string, required) |
client.post("/api/v1/contractors/1234/accounts", {
account: {
account_number: 123456789,
routing_number: 021000021,
name: "Test Bank Account",
account_type: "checking"
})
fetch("https://sandbox.gigwage.com/api/v1/contractors/1234/accounts", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"account": {
"account_number": '123456789',
"routing_number": '021000021',
"name": "Test Bank Account",
"account_type": "checking"
}
})
})
Example JSON response
{
"account": {
"id": 2931,
"routing_number": "021000021",
"name": "Test Bank Account",
"account_type": "checking",
"last4": "6789",
"created_at": "2021-02-28T21:11:39.148Z",
"deactivated_at": null
}
}
GET /api/v1/contractors/{contractor_id}/accounts/{id}
Get details of an existing bank account
Parameters
Parameter | Description |
---|---|
contractor_id | Replace {contractor_id} in the URL with the id of the contractor |
id | Replace {id} in the URL with the id of the bank account |
client.get("/api/v1/contractors/1234/accounts/2931")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1234/accounts/2931", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"account": {
"id": 2931,
"routing_number": "021000021",
"name": "Test Bank Account",
"account_type": "checking",
"last4": "6789",
"created_at": "2021-02-28T21:11:39.148Z",
"deactivated_at": null
}
}
DELETE /api/v1/contractors/{contractor_id}/accounts/{id}
Deactivate contractor's bank account
Parameters
Parameter | Description |
---|---|
contractor_id | Replace {contractor_id} in the URL with the id of the contractor |
id | Replace {id} in the URL with the id of the bank account |
client.delete("/api/v1/contractors/1234/accounts/2931")
fetch("https://sandbox.gigwage.com/api/v1/contractors/1234/accounts/2931", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"account": {
"id": 2931,
"routing_number": "021000021",
"name": "Test Bank Account",
"account_type": "checking",
"last4": "6789",
"created_at": "2021-02-28T21:11:39.148Z",
"deactivated_at": "2021-02-28T21:28:55.939Z"
}
}
Debit Cards
POST /api/v1/contractors/{id}/cards
Add a debit card to an existing contractor
Parameters
Parameter | Description |
---|---|
card | The root of the payload (required) |
name | Debit card's nickname (string, required) |
card_number | Card number (string, required) |
exp_date | Card's expiration date (string, required, YYYYMM) |
client.post('/api/v1/contractors/1234/cards',
card: {
name: 'Test Bank',
card_number: '9401113999999995',
exp_date: '202211'
})
Example JSON response
{
account: {
routing_number: nil,
name: "Test Bank",
account_type: "VISA",
created_at: "2021-04-01T19:01:32.036Z",
deactivated_at: nil
}
}
For other actions on debit cards (show details, deactivation and others) see Bank Accounts
Payments
GET /api/v1/payments/{id}
Returns the details for a single payment, including an array of line item details and the id of the contractor associated with the payment.
client.get("/api/v1/payments/1234")
fetch("https://sandbox.gigwage.com/api/v1/payments/1234", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"payment": {
"id": 1234,
"amount": "12.34",
"line_items": [
{
"id": 2345,
"amount": "12.34",
"reason": "11/5 payroll",
"reimbursement": false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 1
}
}
],
"external_id": null,
"contractor_id": 1004,
"created_at": "2021-05-02T00:18:07.802Z",
"status": "completed",
"metadata": {
"project_id": 1234
}
}
}
GET /api/v1/payments
Returns a list of payments, sorted newest-first
Parameters
All parameters are optional and should be passed as a query string on the URL:
Parameter | Description |
---|---|
size | The number of records to return. Default is 200, max is 200. |
page | For paginated results, the page number to return. For example, ?size=100&page=2 will return payments 101-200. |
contractor_id | Filter results by contractor_id |
client.get("/api/v1/payments?size=1&page=1")
fetch("https://sandbox.gigwage.com/api/v1/payments?size=1&page=1", {
"method": "GET",
"headers": headers
})
Example JSON response
"payments": [
{
"id": 1234,
"amount": "123.0",
"line_items": [
{
"id": 2345,
"amount": "123.0",
"reason": "11/5 payroll",
"reimbursement" :false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 1
}
}
],
"external_id": null,
"contractor_id": 1004,
"created_at": "2021-05-02T00:18:07.802Z",
"status": "completed",
"metadata": {
"project_id": 1234
}
}
]
POST /api/v1/payments
Payments sent on the sandbox environment typically settle within 5-10 minutes regardless of their type but can sometimes take longer.
Please contact support if it takes more than 4 hours.
Sends a new payment to a contractor
Parameters
Parameter | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
payment | The root of the payload (required) | ||||||||||||
nonce | A unique value for idempotency to help prevent accidental duplicate payments (string, required) | ||||||||||||
contractor_id | The id of the contractor to be paid (integer, required) | ||||||||||||
external_id | Your identifier for this payment (string, optional) | ||||||||||||
debit_card | Whether to send payment to a contractor's debit card if possible (boolean, optional) | ||||||||||||
metadata | User defined (hash, optional) | ||||||||||||
line_items | An array of line items (array, required) | ||||||||||||
|
client.post("/api/v1/payments", {
payment: {
nonce: 'abc123',
contractor_id: 1004,
metadata: {
project_id: 1234
},
line_items: [
{
amount: 123.0,
reason: "11/5 payroll",
reimbursement: false,
metadata: {
organization_id: 1
}
}
],
debit_card: nil
}
})
fetch("https://sandbox.gigwage.com/api/v1/payments" {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"payment": {
"nonce": 'abc123',
"contractor_id": 1004,
"metadata": {
"project_id": 1234
},
"line_items": [
{
"amount": 123.0,
"reason": "11/5 payroll",
"reimbursement": false,
"metadata": {
"organization_id": 1
}
}
],
"debit_card": null
}
})
})
Example JSON response
"payments": [
{
"id": 1234,
"amount": "123.0",
"line_items": [
{
"id": 2345,
"amount": "123.0",
"reason": "11/5 payroll",
"reimbursement": false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 1
}
}
],
"external_id": null,
"contractor_id": 1004,
"created_at": "2021-05-02T00:18:07.802Z",
"status": "completed",
"metadata": {
"project_id": 1234
}
}
]
Details on the nonce
parameter: The value will be cached by the API for 24 hours. During this window it must be unique. Once a value has been used, any subsequent requests to this endpoint using the same value for the nonce
will fail. This is by design, in order to prevent the accidental creation of duplicate payments.
Details on the debit_card
parameter: If true, and the payment satisfies requirements for instant payout via debit card, other logic is overridden and the payment will be sent to the contractor's debit card. If false, and the contractor has another payment method available, the payment will not be sent to the contractor's debit card even if the payment meets requirements. If nil
/null
or omitted, payment will be routed according to default logic.
PUT /api/v1/payments/{id}
Update a payment's metadata
Parameters
Parameter | Description |
---|---|
payment | The root of the payload (required) |
metadata | User defined (hash, optional) |
client.put("/payments/1234",
payment: {
metadata: {
project_id: 5678
}
})
fetch("https://sandbox.gigwage.com/api/v1/payments/1234", {
"method": "PUT",
"headers": headers,
"body": JSON.stringify({
"payment": {
"metadata": {
"project_id": 5678
}
}
})
})
Example JSON response
"payments": [
{
"id": 1234,
"amount": "123.0",
"line_items": [
{
"id": 2345,
"amount": "123.0",
"reason": "11/5 payroll",
"reimbursement": false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 1
}
}
],
"external_id": null,
"contractor_id": 1004,
"created_at": "2021-05-02T00:18:07.802Z",
"status": "completed",
"metadata": {
"project_id": 5678
}
}
]
POST /api/v1/payments/{id}/retry
Retry a canceled or returned payment.
client.post("/api/v1/payments/1234/retry")
fetch("https://sandbox.gigwage.com/api/v1/payments/1234/retry", {
"method": "POST",
"headers": headers
})
Example JSON response
{
"payment": {
"id": 1234,
"amount": "12.34",
"line_items": [
{
"id": 2345,
"amount": "12.34",
"reason": "11/5 payroll",
"reimbursement": false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 1
}
}
],
"external_id": null,
"contractor_id": 1004,
"created_at": "2021-05-02T00:18:07.802Z",
"status": "transferring",
"metadata": {
"project_id": 1234
}
}
}
DELETE /api/v1/payments/{id}
Attempts to cancel a payment.
client.delete("/api/v1/payments/1234")
fetch("https://sandbox.gigwage.com/api/v1/payments/1234", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"payment": {
"id": 1234,
"amount": "12.34",
"line_items": [
{
"id": 2345,
"amount": "12.34",
"reason": "11/5 payroll",
"reimbursement": false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 1
}
}
],
"external_id": null,
"contractor_id": 1004,
"created_at": "2021-05-02T00:18:07.802Z",
"status": "canceled",
"metadata": {
"project_id": 1234
}
}
}
Line Items
PUT /api/v1/line_items/{id}
Update a line item's metadata
Parameters
Parameter | Description |
---|---|
line_item | The root of the payload (required) |
metadata | User defined (hash, optional) |
client.put("/line_items/1234",
line_item: {
metadata: {
organization_id: 2
}
})
fetch("https://sandbox.gigwage.com/api/v1/line_items/1234", {
"method": "PUT",
"headers": headers,
"body": JSON.stringify({
"line_item": {
"metadata": {
"organization_id": 2
}
}
})
})
Example JSON response
{
"line_item": {
"id": 1234,
"amount": "10.0",
"reason": "tst",
"reimbursement": false,
"job_id": null,
"external_id": null,
"metadata": {
"organization_id": 2
}
}
}
Batches
GET /api/v1/batches
Returns a list of batches, sorted newest-first
client.get("/api/v1/batches")
fetch("https://sandbox.gigwage.com/api/v1/batches", {
"method": "GET",
"headers": headers
})
Example JSON response
"batches": [
{
"id": 1234,
"payments": [
{
"id": 1234,
"amount": "120.0",
"line_items": [
{
"id": 1234,
"amount": "120.0",
"reason": "Test",
"reimbursement": false,
"job_id": null,
"external_id": null
}
],
"contractor_id": 1234,
"created_at": "2021-03-16T16:53:45.329Z",
"status": "pending",
"external_id": null
}
]
}
]
POST /api/v1/batches
Creates a new batch of payments
Parameters
Parameter | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
batch | The root of the payload (required) | ||||||||||
nonce | A unique value for idempotency to help prevent accidental duplicate payments (string, required) | ||||||||||
notes | User defined (string, optional) | ||||||||||
payments | An array of payments (array, required) | ||||||||||
contractor_id | The id of the contractor to be paid (integer, required) | ||||||||||
external_id | Your identifier for this payment (string, optional) | ||||||||||
debit_card | Whether to send payment to a contractor's debit card if possible (boolean, optional) | ||||||||||
line_items | An array of line items (array, required) | ||||||||||
|
client.post("batches", batch: {
nonce: "abc123",
payments: [{
contractor_id: 1,
debit_card: false,
line_items: [{
amount: 10,
reason: "Test 1",
reimbursement: false
}]
}, {
contractor_id: 2,
debit_card: false,
line_items: [{
amount: 20,
reason: "Test 2",
reimbursement: false
}]
}]
})
fetch("https://sandbox.gigwage.com/api/v1/batches", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"batch": {
"nonce": "abc123",
"payments": [{
"contractor_id": 1,
"debit_card": false,
"line_items": [{
"amount": 10,
"reason": "Test 1",
"reimbursement": false
}]
}, {
"contractor_id": 2,
"debit_card": false,
"line_items": [{
"amount": 20,
"reason": "Test 2",
"reimbursement": false
}]
}]
}
})
})
Example JSON response
{
"batch": {
"id": 1,
"payments": [{
"id": 1,
"amount": "10.0",
"line_items": [{
"id": 54743,
"amount": "10.0",
"reason": "Test 1",
"reimbursement": false,
"job_id": null,
"external_id": null
}],
"contractor_id": 12217,
"created_at": "2021-03-17T22:35:24.802Z",
"status": "pending",
"external_id": null
}, {
"id": 2,
"amount": "20.0",
"line_items": [{
"id": 54744,
"amount": "20.0",
"reason": "Test 2",
"reimbursement": false,
"job_id": null,
"external_id": null
}],
"contractor_id": 12491,
"created_at": "2021-03-17T22:35:25.034Z",
"status": "pending",
"external_id": null
}],
"payments_count": 2,
"notes": null,
"created_at": "2021-03-17T22:35:24.776Z"
}
}
Details on the nonce
parameter: The value will be cached by the API for 24 hours. During this window it must be unique. Once a value has been used, any subsequent requests to this endpoint using the same value for the nonce
will fail. This is by design, in order to prevent the accidental creation of duplicate payments.
Details on the debit_card
parameter: If true, and the payment satisfies requirements for instant payout via debit card, other logic is overridden and the payment will be sent to the contractor's debit card. If false, and the contractor has another payment method available, the payment will not be sent to the contractor's debit card even if the payment meets requirements. If nil
/null
or omitted, payment will be routed according to default logic.
GET /api/v1/batches/1
Returns the details of a single batch batch
client.get("/api/v1/batches/1")
fetch("https://sandbox.gigwage.com/api/v1/batches/1", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"batch": {
"id": 1,
"payments": [{
"id": 1,
"amount": "10.0",
"line_items": [{
"id": 54743,
"amount": "10.0",
"reason": "Test 1",
"reimbursement": false,
"job_id": null,
"external_id": null
}],
"contractor_id": 12217,
"created_at": "2021-03-17T22:35:24.802Z",
"status": "pending",
"external_id": null
}, {
"id": 2,
"amount": "20.0",
"line_items": [{
"id": 54744,
"amount": "20.0",
"reason": "Test 2",
"reimbursement": false,
"job_id": null,
"external_id": null
}],
"contractor_id": 12491,
"created_at": "2021-03-17T22:35:25.034Z",
"status": "pending",
"external_id": null
}],
"payments_count": 2,
"notes": null,
"created_at": "2021-03-17T22:35:24.776Z"
}
}
GET /api/v1/batches/1/payments
Returns the payments from a single batch batch
client.get("/api/v1/batches/1/payments")
fetch("https://sandbox.gigwage.com/api/v1/batches/1/payments", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"payments": [{
"id": 1,
"amount": "10.0",
"line_items": [{
"id": 54743,
"amount": "10.0",
"reason": "Test 1",
"reimbursement": false,
"job_id": null,
"external_id": null
}],
"contractor_id": 12217,
"created_at": "2021-03-17T22:35:24.802Z",
"status": "pending",
"external_id": null
}, {
"id": 2,
"amount": "20.0",
"line_items": [{
"id": 54744,
"amount": "20.0",
"reason": "Test 2",
"reimbursement": false,
"job_id": null,
"external_id": null
}],
"contractor_id": 12491,
"created_at": "2021-03-17T22:35:25.034Z",
"status": "pending",
"external_id": null
}]
}
Transfers
GET /api/v1/transfers
Get a list of all transfers
client.get("/api/v1/transfers")
fetch("https://sandbox.gigwage.com/api/v1/transfers", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"transfer": {
"id": 52585,
"direction": "fund",
"amount": "100.0",
"status": "CREATED",
"created_at": "2021-02-28T21:42:54.270Z"
}
}
POST /api/v1/transfers
Create a transfer transaction
Parameters
Parameter | Description |
---|---|
transfer | The root of the payload (required) |
amount | Dollar amount for the transfer (decimal, required) |
direction | fund or withdraw (string, required) |
nonce | A unique value for idempotency to help prevent accidental duplicate payments (string, required) |
client.post("/api/v1/transfers", {
transfer: {
amount: 100.00,
direction: "fund",
nonce: 'abc123'
})
fetch("https://sandbox.gigwage.com/api/v1/transfers", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"transfer": {
"amount": 100.00,
"direction": "fund",
"nonce": 'abc123'
}
})
})
Example JSON response
{
"transfer": {
"id": 52585,
"direction": "fund",
"amount": "100.0",
"status": "CREATED",
"created_at": "2021-02-28T21:42:54.270Z"
}
}
GET /api/v1/transfers/{id}
Get details of an existing transfer
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the transfer |
client.get("/api/v1/transfers/52585")
fetch("https://sandbox.gigwage.com/api/v1/transfers/52585", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"transfer": {
"id": 52585,
"direction": "fund",
"amount": "100.0",
"status": "CREATED",
"created_at": "2021-02-28T21:42:54.270Z"
}
}
DELETE /api/v1/transfers/{id}
Attempt to cancel a transfer
Parameters
Parameter | Description |
---|---|
id | Replace {id} in the URL with the id of the transfer |
client.delete("/api/v1/transfers/52585")
fetch("https://sandbox.gigwage.com/api/v1/transfers/52585", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"transfer": {
"id": 52585,
"direction": "fund",
"amount": "100.0",
"status": "CANCELED",
"created_at": "2021-02-28T21:42:54.270Z"
}
}
Account Balance
GET /api/v1/balance
Returns the current and available balance for the account
client.get("/api/v1/balance")
fetch("https://sandbox.gigwage.com/api/v1/balance", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"gigwage_account": {
"current_balance": "100.0",
"available_balance": "100.0"
}
}
1099s
GET /api/v1/1099s/{id}
Get details of a 1099
client.get("/api/v1/1099s/1234")
fetch("https://sandbox.gigwage.com/api/v1/1099s/1234", {
"method": "GET",
"headers": headers
})
Example JSON response
"1099": {
"id": 1234,
"contractor_id": 1004,
"year": 2021,
"status": "draft",
"type": "NEC",
"box1": 12.12,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}
GET /api/v1/1099s
Returns a list of 1099s, sorted newest-first
client.get("/api/v1/1099s")
fetch("https://sandbox.gigwage.com/api/v1/1099s", {
"method": "GET",
"headers": headers
})
Example JSON response
"1099s": [
{
"id": 1234,
"contractor_id": 1004,
"year": 2021,
"status": "draft",
"type": "K",
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null,
"box1a": 1500.00,
"box1b": null,
"box3": null,
"box5c": null,
"box5d": null,
"box5e": null,
"box5f": null,
"box5g": null,
"box5h": null,
"box5i": null,
"box5j": null,
"box5k": null,
"box5l": null,
"box8a": null,
"box8b": null
},
{
"id": 1235,
"contractor_id": 1005,
"year": 2021,
"status": "draft",
"type": "NEC",
"box1": 750.50,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}
]}
POST /api/v1/1099s
Create a 1099 for a contractor.
Parameters for 1099-K
For more information on box values please visit the IRS
Parameter | Description |
---|---|
contractor_id | The ID of the contractor (integer, required) |
type | Type of 1099 to create (string, required, K) |
box1a | Box 1a (decimal) |
box1b | Box 1b (decimal) |
box2 | Box 2 (string) |
box3 | Box 3 (decimal) |
box4 | Box 4 (decimal) |
box5a | Box 5a (decimal) |
box5b | Box 5b (decimal) |
box5c | Box 5c (decimal) |
box5d | Box 5d (decimal) |
box5e | Box 5e (decimal) |
box5f | Box 5f (decimal) |
box5g | Box 5g (decimal) |
box5h | Box 5h (decimal) |
box5i | Box 5i (decimal) |
box5j | Box 5j (decimal) |
box5k | Box 5k (decimal) |
box5l | Box 5l (decimal) |
box6a | Box 6a (string) |
box6b | Box 6b (string) |
box7a | Box 7a (string) |
box7b | Box 7b (string) |
box8a | Box 8a (decimal) |
box8b | Box 8b (decimal) |
Parameters for 1099-NEC
For more information on box values please visit the IRS
Parameter | Description |
---|---|
contractor_id | The ID of the contractor (integer, required) |
type | Type of 1099 to create (string, required, NEC) |
box1 | Box 1 (decimal) |
box2 | Box 2 (boolean) |
box4 | Box 4 (decimal) |
box5a | Box 5a (decimal) |
box5b | Box 5b (decimal) |
box6a | Box 6a (string) |
box6b | Box 6b (string) |
box7a | Box 7a (decimal) |
box7b | Box 7b (decimal) |
client.post("/api/v1/1099s", '1099': {
contractor_id: 1004,
box1: 750.50,
type: "NEC"
})
fetch("https://sandbox.gigwage.com/api/v1/1099s", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"1099": {
"contractor_id": 1004,
"box1": 750.50,
"type": "NEC"
}
})
})
Example JSON response
"1099": {
"id": 1235,
"contractor_id": 1005,
"year": 2021,
"status": "draft",
"type": "NEC",
"box1": 750.50,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}
POST /api/v1/1099s/{id}/approve
Mark 1099 as ready to submit to the IRS
client.post("/api/v1/1099s/1234/approve")
fetch("https://sandbox.gigwage.com/api/v1/1099s/1234/approve", {
"method": "POST",
"headers": headers
})
Example JSON response
"1099": {
"id": 1235,
"contractor_id": 1005,
"year": 2021,
"status": "ready",
"type": "NEC",
"box1": 750.50,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}
POST /api/v1/1099s/{id}/submit
Submit 1099 to the IRS
client.post("/api/v1/1099s/1234/submit")
fetch("https://sandbox.gigwage.com/api/v1/1099s/1234/submit", {
"method": "POST",
"headers": headers
})
Example JSON response
"1099": {
"id": 1234,
"contractor_id": 1004,
"year": 2021,
"status": "submitted",
"type": "NEC",
"box1": 12.12,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}
GET /api/v1/1099s/{id}/retrieve
Returns the URL to a PDF of a submitted 1099. The URL expires in 1 hour
client.get("/api/v1/1099s/1234/retrieve")
fetch("https://sandbox.gigwage.com/api/v1/1099s/1234/retrieve", {
"method": "GET",
"headers": headers
})
Example JSON Response
{
"url": "a very long URL",
"id": 25,
"status": "submitted"
}
DELETE /api/v1/1099s/{id}
Delete 1099
client.delete("/api/v1/1099s/1234")
fetch("https://sandbox.gigwage.com/api/v1/1099s/1234", {
"method": "DELETE",
"headers": headers
})
Example JSON response
"1099": {
"id": 1234,
"contractor_id": 1004,
"year": 2021,
"status": "submitted",
"type": "NEC",
"box1": 12.12,
"box2": null,
"box4": null,
"box5a": null,
"box5b": null,
"box6a": null,
"box6b": null,
"box7a": null,
"box7b": null
}
API keys
GET /api/v1/api_keys
Get a list of all API keys
client.get("/api/v1/api_keys")
fetch("https://sandbox.gigwage.com/api/v1/api_keys", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"api_keys": [
{
"name": "Default",
"key": "12a5aefc38209c9aa69d66d81453874f",
"revoked_at": null,
"created_at": "2021-02-25T20:18:07.853Z"
}
]
}
POST /api/v1/api_keys
Create a new API key. Note, this is the only time you'll get the secret
Parameters
Parameter | Description |
---|---|
api_key | The root of the payload (required) |
name | API key name (string, required) |
client.post("/api/v1/api_keys", {
api_key: {
name: "Default"
})
fetch("https://sandbox.gigwage.com/api/v1/api_keys", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"api_key": {
"name": "Default"
}
})
})
Example JSON response
{
"api_key": {
"name": "Default",
"key": "12a5aefc38209c9aa69d66d81453874f",
"secret": "683d5b2cdeed04daf2e570f6084cb8cab663870fd15f49e4eb8362884c1fe52038da2409e6db4a7c1cbc449e512c3cb635cd10b6844228508a0eba8e118d84cf",
"revoked_at": null,
"created_at": "2021-02-25T20:18:07.853Z"
}
}
GET /api/v1/api_keys/{key}
Get details of an existing API key
Parameters
Parameter | Description |
---|---|
key | Replace {key} in the URL with the key |
client.get("/api/v1/api_keys/12a5aefc38209c9aa69d66d81453874f")
fetch("https://sandbox.gigwage.com/api/v1/api_keys/12a5aefc38209c9aa69d66d81453874f", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"api_key": {
"name": "Default",
"key": "12a5aefc38209c9aa69d66d81453874f",
"revoked_at": null,
"created_at": "2021-02-25T20:18:07.853Z"
}
}
DELETE /api/v1/api_keys/{key}
Revoke an API key. Note, can't revoke the one being used to connect.
Parameters
Parameter | Description |
---|---|
key | Replace {key} in the URL with the key |
client.delete("/api/v1/api_keys/a8528b3b2c4b57a7f98d94002650c870")
fetch("https://sandbox.gigwage.com/api/v1/api_keys/12a5aefc38209c9aa69d66d81453874f", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"api_key": {
"name": "Default",
"key": "a8528b3b2c4b57a7f98d94002650c870",
"revoked_at": "2021-02-28T22:16:27.843Z",
"created_at": "2021-02-25T20:18:07.853Z"
}
}
Allowed Domains
Allow emails from sandbox to be sent to these domains.
By default, all emails are blocked in the sandbox environment. You can allow up to 3 domains so that emails are sent to any of them.
Public domains (e.g. gmail, yahoo) are not allowed.
GET /api/v1/allowed_domains
List all allowed domains
client.get("/api/v1/allowed_domains")
fetch("https://sandbox.gigwage.com/api/v1/allowed_domains", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"allowed_domains": [ {
"id": 1,
"domain": "example.com",
"created_at": "2022-03-23T19:06:04.662Z"
} ]
}
GET /api/v1/allowed_domains/{id}
Get details of allowed domain
client.get("/api/v1/allowed_domains/1")
fetch("https://sandbox.gigwage.com/api/v1/allowed_domains/1", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"allowed_domain": {
"id": 1,
"domain": "example.com",
"created_at": "2022-03-23T19:06:04.662Z"
}
}
POST /api/v1/allowed_domains
Allow sandbox to send emails to a domain.
client.post("/api/v1/allowed_domains", {
"allowed_domain": {
"domain": "example.com"
}
}
fetch("https://sandbox.gigwage.com/api/v1/allowed_domains/1", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"allowed_domain": {
"domain": "example.com"
}
})
})
Example JSON response
{
"allowed_domain": {
"id": 1,
"domain": "example.com",
"created_at": "2022-03-23T19:06:04.662Z"
}
}
DELETE /api/v1/allowed_domains/{id}
Remove domain from allowed list
client.delete("/api/v1/allowed_domains", {
"allowed_domain": {
"domain": "example.com"
}
}
fetch("https://sandbox.gigwage.com/api/v1/allowed_domains/1", {
"method": "DELETE",
"headers": headers,
"body": JSON.stringify({
"allowed_domain": {
"domain": "example.com"
}
})
})
Example JSON response
{
"allowed_domain": {
"id": 1,
"domain": "example.com",
"created_at": "2022-03-23T19:06:04.662Z"
}
}
Subscriptions
Manage subscriptions for webhooks.
Available types are Payment, TIN Check, 1099 and Partnership signup.
GET /api/v1/subscriptions
Returns a list of all subscriptions
client.get("/api/v1/subscriptions")
fetch("https://sandbox.gigwage.com/api/v1/subscriptions", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"subscriptions": [
{
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/webhooks",
"deactivated_at": null,
"created_at": "2022-03-04T17:28:31.194Z"
},
{
"id": 2,
"webhook_type": "tin_check",
"url": "https://example.com/webhooks",
"deactivated_at": null,
"created_at": "2022-03-08T21:34:23.791Z"
}
]
}
POST /api/v1/subscriptions
Subscribe to webhooks of the chosen type. Please note that multiple consecutive failures to deliver webhooks will deactivate this subscription, and it will need to be reactivated. See PUT below.
Parameter | Description |
---|---|
webhook_type | Type of webhook you wish to get updates for. Accepted values are payment , tin_check , partner_sign_up and 1099 |
url | URL to send the webhooks to |
client.post("/api/v1/subscriptions", {
subscription: {
webhook_type: "payment",
url: 'https://example.com/webhooks'
}
})
fetch("https://sandbox.gigwage.com/api/v1/subscriptions", {
"method": "POST",
"headers": headers,
"body": JSON.stringify({
"subscription": {
"webhook_type": "payment",
"url": 'https://example.com/webhooks'
}
})
})
Example JSON response
{
"subscription": {
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/webhooks",
"deactivated_at": null,
"created_at": "2022-03-04T17:28:31.194Z"
}
}
GET /api/v1/subscriptions/{id}
Get the details of a subscription
client.get("/api/v1/subscriptions/1")
fetch("https://sandbox.gigwage.com/api/v1/payments/1", {
"method": "GET",
"headers": headers
})
Example JSON response
{
"subscription": {
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/webhooks",
"deactivated_at": null,
"created_at": "2022-03-04T17:28:31.194Z"
}
}
DELETE /api/v1/subscriptions/{id}/deactivate
Deactivates a subscription
client.delete("/api/v1/subscriptions/1/deactivate")
fetch("https://sandbox.gigwage.com/api/v1/payments/1/deactivate", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"subscription": {
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/webhooks",
"deactivated_at": "2022-03-08T22:23:22.089Z",
"created_at": "2022-03-04T17:28:31.194Z"
}
}
PUT /api/v1/payments/{id}
Reactivate an inactive subscription
client.put("/api/v1/subscriptions/1")
fetch("https://sandbox.gigwage.com/api/v1/payments/1", {
"method": "PUT",
"headers": headers
})
Example JSON response
{
"subscription": {
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/webhooks",
"deactivated_at": null,
"created_at": "2022-03-04T17:28:31.194Z"
}
}
PATCH /api/v1/subscriptions/{id}
Change the URL to send webhooks to
client.patch("/api/v1/subscriptions/1", {
subscription: {
url: 'https://example.com/payment_webhooks'
}
})
fetch("https://sandbox.gigwage.com/api/v1/subscriptions/1", {
"method": "PATCH",
"headers": headers,
"body": JSON.stringify({
"subscription": {
"url": 'https://example.com/payment_webhooks'
}
})
})
Example JSON response
{
"subscription": {
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/payment_webhooks",
"deactivated_at": null,
"created_at": "2022-03-04T17:28:31.194Z"
}
}
DELETE /api/v1/subscriptions/{id}
Permanently remove a subscription
client.delete("/api/v1/subscriptions/1")
fetch("https://sandbox.gigwage.com/api/v1/payments/1", {
"method": "DELETE",
"headers": headers
})
Example JSON response
{
"subscription": {
"id": 1,
"webhook_type": "payment",
"url": "https://example.com/webhooks",
"deactivated_at": null,
"created_at": "2022-03-04T17:28:31.194Z"
}
}
Webhooks
To get started with webhooks, subscribe to the type you want to get updates for.
Payment
Sends a webhook whenever a payment status changes.
Possible statuses
- pending
- enqueued
- funding
- awaiting_contractor_account
- transferring
- pending_cancelation
- completed
- returned
- canceled
- action_required
- refunded
Example JSON response
{
"type": "Payment",
"id": 1234,
"field": "status",
"from": "transferring",
"to": "completed",
"at": "2021-05-02T00:18:07.802Z"
}
TIN Check
Send a webhook whenever a TIN check status changes.
Possible statuses
- pending
- success
- failure
- review
Example JSON response
{
"type": "TinCheck",
"id": 1234,
"field": "status",
"from": "pending",
"to": "success",
"at": "2021-05-02T00:18:07.802Z"
}
1099
Validation
1099s have a 2 step validation process. The first does a quick check for required fields and the second is sent of to a third party for validation.
With the third party validation, the 1099 will be in a validating
state for a few minutes. A webhook will be sent when that validation is finished.
If any errors are encountered during validation, an extra errors
array will be added with the details.
Possible statuses
- ready
- problem
Example JSON response
{
"type": "1099",
"id": 1234,
"field": "status",
"from": "validating",
"to": "ready",
"at": "2021-05-02T00:18:07.802Z"
}
Submit
When you submit a 1099, the status will change to submitting
and it will stay that way until the process finishes. A webhok will be sent when complete.
If any errors are encountered during submission, an extra errors
array will be added with the details.
Possible statuses
- submitted
- problem
Example JSON response
{
"type": "1099",
"id": 1234,
"field": "status",
"from": "submitting",
"to": "submitted",
"at": "2021-05-02T00:18:07.802Z"
}
Partner Signup
Sends a webhook whenever a business signs up using your partnership link and also updates on their compliance process.
Possible statuses
- signed_up
- accepted
- completed
- rejected
The completed
status is the last step and is sent when the business adds their bank account and is ready to process payments.
Example JSON response
{
"type": "Business",
"id": 1234,
"field": "status",
"from": "accepted",
"to": "completed",
"at": "2021-05-02T00:18:07.802Z"
}
Headers
Webhooks will contain a X-GIGWAGE-SIGNATURE
in the header that should be used to verify
the authenticity of the request. It is generated in the same way documented on the Signature of authentication but without the timestamp
Errors
The Gig Wage API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- Not for you. |
404 | Not Found -- The resource you requested could not be found. |
420 | Enhance your calm -- Exceeded API ratelimit. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Extras
Entity
Accepted values for vendor entity
- LLC
- CORP
- PARTNERSHIP
- SOLE-PROPRIETORSHIP
Industry
Accepted values for vendor industry
- Not Known
- Aerospace/Defense
- Airport
- Arts & Entertainment
- Automobiles and Parts
- Automotive
- Bank & Financial Services
- Bank/Financial Institution
- Bar
- Biotechnology
- Book Store
- Business Services
- Cause
- Chemicals
- Club
- Community Organization
- Community/Government
- Company
- Computers/Technology
- Concert Venue
- Consulting/Business Services
- Doctor
- Education
- Elementary School
- Energy/Utility
- Engineering/Construction
- Event Planning/Event Services
- Farming/Agriculture
- Food/Beverages
- Food/Grocery
- Government Organization
- Health/Beauty
- Health/Medical/Pharmaceuticals
- Health/Medical/Pharmacy
- Home Improvement
- Hospital/Clinic
- Hotel
- Industrials
- Insurance Company
- Internet/Software
- Landmark
- Lawyer
- Legal/Law
- Library
- Licensed Financial Representative
- Local Business
- Media/News/Publishing
- Middle School
- Mining/Materials
- Movie Theater
- Museum/Art Gallery
- Non-Governmental Organization (NGO)
- Non-Profit Organization
- Organization
- Outdoor Gear/Sporting Goods
- Pet Services
- Political Organization
- Political Party
- Preschool
- Professional Services
- Public Places
- Real Estate
- Religious Organization
- Restaurant/Cafe
- Retail and Consumer Merchandise
- School
- Shopping/Retail
- Small Business
- Spas/Beauty/Personal Care
- Sports Venue
- Sports/Recreation/Activities
- Telecommunication
- Tours/Sightseeing
- Train Station
- Transport/Freight
- Transportation
- Travel/Leisure
- University
Tax Classification
Accepted values for W9 tax_classification
- single_member_llc (Individual/sole proprietor or single member LLC)
- c_corporation (C Corporation)
- s_corporation (S Corporation)
- partnership (Partnership)
- trust_estate (Trust/Estate)
- limited_liability_company (LLC)
- other