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)
facta_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) 
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,
    facta_reporting_exemption_code: null
    tin_check_status: 'failure',
    tin_check_reason: 'TIN entered is not currently issued.'
  }

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)
facta_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) 
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,
    facta_reporting_exemption_code: null
    tin_check_status: 'failure',
    tin_check_reason: 'TIN entered is not currently issued.'
  }

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,
    facta_reporting_exemption_code: null,
    tin_check_status: 'failure',
    tin_check_reason: 'TIN entered is not currently issued.'
  }

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

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("http://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: nil,
    external_id: nil,
    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: nil,
            external_id: nil
          }
        ],
        contractor_id: 1234,
        created_at: "2021-03-16T16:53:45.329Z",
        status: "pending",
        external_id: nil
      }
    ]
  }
]

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: nil,
        external_id: nil
      }],
      contractor_id: 12217,
      created_at: "2021-03-17T22:35:24.802Z",
      status: "pending",
      external_id: nil
    }, {
      id: 2,
      amount: "20.0",
      line_items: [{
        id: 54744,
        amount: "20.0",
        reason: "Test 2",
        reimbursement: false,
        job_id: nil,
        external_id: nil
      }],
      contractor_id: 12491,
      created_at: "2021-03-17T22:35:25.034Z",
      status: "pending",
      external_id: nil
    }],
    payments_count: 2,
    notes: nil,
    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: nil,
        external_id: nil
      }],
      contractor_id: 12217,
      created_at: "2021-03-17T22:35:24.802Z",
      status: "pending",
      external_id: nil
    }, {
      id: 2,
      amount: "20.0",
      line_items: [{
        id: 54744,
        amount: "20.0",
        reason: "Test 2",
        reimbursement: false,
        job_id: nil,
        external_id: nil
      }],
      contractor_id: 12491,
      created_at: "2021-03-17T22:35:25.034Z",
      status: "pending",
      external_id: nil
    }],
    payments_count: 2,
    notes: nil,
    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: nil,
      external_id: nil
    }],
    contractor_id: 12217,
    created_at: "2021-03-17T22:35:24.802Z",
    status: "pending",
    external_id: nil
  }, {
    id: 2,
    amount: "20.0",
    line_items: [{
      id: 54744,
      amount: "20.0",
      reason: "Test 2",
      reimbursement: false,
      job_id: nil,
      external_id: nil
    }],
    contractor_id: 12491,
    created_at: "2021-03-17T22:35:25.034Z",
    status: "pending",
    external_id: nil
  }]
}

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

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

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