NAV Navbar
ruby javascript

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 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:

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)
email The contractor's email (string, required)
send_invite Invite the contractor to register their account (boolean, optional, false by default) 
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)
email 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)
FieldDescription
amount The amount of the line item in dollars (decimal, required)
job_id User defined (string, optional)
reason The reason for this line item (string, optional)
reimbursement Whether this line item is a reimbursement (boolean, optional)
metadataUser defined (hash, optional)
 
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)
FieldDescription
amount The amount of the line item in dollars (decimal, required)
job_id User defined (string, optional)
reason The reason for this line item (string, optional)
reimbursement Whether this line item is a reimbursement (boolean, optional)
 
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, required)
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, required)
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)

Parameters for 1099-MISC

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, MISC)
box1 Box 1 (decimal)
box2 Box 2 (decimal)
box4 Box 4 (decimal)
box5 Box 5 (decimal)
box6 Box 6 (decimal)
box7 Box 7 (boolean)
box8 Box 8 (decimal)
box9 Box 9 (decimal)
box10 Box 10 (decimal)
box11 Box 11 (decimal)
box12 Box 12 (decimal)
box13 Box 13 (boolean)
box14 Box 14 (decimal)
box15 Box 15 (decimal)
box16a Box 16, line 1 (decimal)
box16b Box 16, line 2 (decimal)
box17a Box 17, line 1 (string)
box17b Box 17, line 2 (string)
box18a Box 18, line 1 (decimal)
box18b Box 18, line 2 (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
ruby javascript