NAV Navbar
ruby javascript

Introduction

Thanks for your interest in the Gig Wage API. We look forward to seeing what you build!

In order to get an API key for your integration, please complete the .

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: "2019-05-03T22:18:16.965Z",
    invitation_accepted_at: "2019-06-03T22:18:16.965Z",
    created_at: "2019-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. 
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: "2019-05-03T22:18:16.965Z",
      invitation_accepted_at: "2019-06-03T22:18:16.965Z",
      created_at: "2019-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) 
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: "2019-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: "2019-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: "2019-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: "2019-05-03T22:18:16.965Z",
    invitation_accepted_at: "2019-06-03T22:18:16.965Z",
    created_at: "2019-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: "2019-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"
  }
}

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",
  }
}

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: "2019-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: "2019-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: "2019-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: "2019-05-02T00:18:07.802Z",
    status: "completed",
    metadata: {
      project_id: 5678
    }
  }
]

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: "2019-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)
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"
  }
}

Webhooks

To get started with webhooks, contact us over slack. We'll need a URL to send the webhooks to, and also the type of webhooks you are looking to subscribe to.

Available types are Payment, TIN Check, 1099 and Partnership signup.

Payment

Sends a webhook whenever a payment status changes.

Possible statuses

Example JSON response

{
  type: "Payment",
  id: 1234,
  field: "status",
  from: "transferring",
  to: "completed",
  at: "2019-05-02T00:18:07.802Z"
}

TIN Check

Send a webhook whenever a TIN check status changes.

Possible statuses

Example JSON response

{
  type: "TinCheck",
  id: 1234,
  field: "status",
  from: "pending",
  to: "success",
  at: "2019-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.

Possible statuses

Example JSON response

{
  type: "1099",
  id: 1234,
  field: "status",
  from: "validating",
  to: "ready",
  at: "2019-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.

Possible statuses

Example JSON response

{
  type: "1099",
  id: 1234,
  field: "status",
  from: "submitting",
  to: "submitted",
  at: "2019-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

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

Industry

Accepted values for vendor industry

Tax Classification

Accepted values for W9 tax_classification

ruby javascript