MyGigsters API Documentation

Authentication

All employee endpoints require Basic Authentication using your API Key credentials. For detailed authentication instructions, please refer to the Authentication guide.

Create Employee

POST/v1/employees

Overview

Creates a new employee record and stores static employee information in the database. This information will be used when submitting contributions, so you only need to provide variable data (amounts, pay periods) in contribution requests.

Employee Data Stored

The following static information is stored:

Name (first name, last name)
Gender
Date of birth
Address
Email
Tax File Number (TFN)
Superannuation identifiers (USI, memberNumber, employmentPayrollNumber)
Optional employee ABN (if applicable)

USI, memberNumber, and employmentPayrollNumber are required for onboarding and are later reused when building SuperChoice validation and submission payloads.

Use Case

Onboard a new employee using this endpoint
Store the returned employee ID
Use the employee ID when submitting contributions

Request Body

Required: Yes

Content-Type: application/json

Parameter

Type

Description

email *

string

Employee email address (must be valid email format)

name *

object

Employee name

Parameter	Type	Description
firstName*	string	First or given name of the fund member as registered with their superannuation fund. Must match the name on the member's fund account for successful contribution allocation.
lastName*	string	Last name or surname of the fund member as registered with their superannuation fund. Must match exactly for the contribution to be successfully allocated.

gender *

string (NOT_STATED, MALE, FEMALE, INDETERMINATE)

Employee gender. Valid values: NOT_STATED, MALE, FEMALE, INDETERMINATE

dob *

object

Date of birth

Parameter	Type	Description
year*	number	Birth year (4 digits). Used along with month and day to verify member identity with the fund. Members must be at least 15 years old to receive superannuation contributions.
month*	string (JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER)	Birth month as a full month name (uppercase). Must match the member's date of birth registered with their fund.
day*	number	Birth day of the month (1-31). Ensure this matches the fund's records for successful member identification.

address *

object

Employee address

Parameter

Type

Description

australianAddress*

object

Australian residential address of the fund member. Used for member identification and correspondence if needed.

Parameter	Type	Description
line1*	string	Primary address line - typically street number and street name. Example: "640 Gordon Street" or "Unit 5, 123 Main Road"
line2*	string	Secondary address line - additional address information if needed (e.g., building name, floor). Use a single space " " if not applicable.
line3*	string	Tertiary address line - rarely used, for complex addresses. Use a single space " " if not applicable.
line4*	string	Quaternary address line - very rarely used. Use a single space " " if not applicable.
suburb*	string	Suburb or locality name. Must be a valid Australian suburb name. Use uppercase for consistency with Australia Post standards.
postCode*	string	Australian postcode - a 4-digit number identifying the postal delivery area. Must be a valid Australian postcode.
stateOrTerritory*	string (NSW, VIC, QLD, SA, WA, TAS, NT, ACT)	Australian state or territory abbreviation. Valid values: NSW, VIC, QLD, SA, WA, TAS, NT, ACT
countryCode*	string (AU)	ISO 3166-1 alpha-2 country code. Must be "AU" for Australian addresses. International addresses are not currently supported.

taxFileNumber *

string

Tax File Number (TFN)

usi *

string

Unique Superannuation Identifier (USI) for the employee’s chosen super fund/product. This will be used when building validation and submission payloads to SuperChoice.

memberNumber *

string

Member number issued by the superannuation fund for this employee. This will be sent in the SuperChoice member payload and used by the fund to directly match contributions to the member’s account.

employmentPayrollNumber *

string

Employment / payroll number used by the employer to identify this employee in payroll systems. This will be sent as the employmentPayrollNumber field to SuperChoice.

abn

string

Australian Business Number (ABN) for the employee (typically contractors). Stored for reference only and **not** sent to SuperChoice APIs.

Responses

Content-Type: application/json

Response Code

Description

Schema

201

Employee created successfully

Parameter

Type

Description

employeeId

string

Employee ID

string

Employee email address (optional)

name

object

Employee name

Parameter	Type	Description
firstName	string	First or given name of the fund member as registered with their superannuation fund. Must match the name on the member's fund account for successful contribution allocation.
lastName	string	Last name or surname of the fund member as registered with their superannuation fund. Must match exactly for the contribution to be successfully allocated.

gender

string

Employee gender. Valid values: NOT_STATED, MALE, FEMALE, INDETERMINATE

dob

object

Date of birth

Parameter	Type	Description
year	number	Birth year (4 digits). Used along with month and day to verify member identity with the fund. Members must be at least 15 years old to receive superannuation contributions.
month	string	Birth month as a full month name (uppercase). Must match the member's date of birth registered with their fund.
day	number	Birth day of the month (1-31). Ensure this matches the fund's records for successful member identification.

address

object

Employee address

Parameter	Type	Description
australianAddress	object	Australian residential address of the fund member. Used for member identification and correspondence if needed.

taxFileNumber

string

Tax File Number (TFN)

employerId

string

Employer ID this employee belongs to

usi

string

Unique Superannuation Identifier (USI) for the employee’s chosen super fund/product. Used when building validation and submission payloads to SuperChoice.

memberNumber

string

Member number issued by the superannuation fund for this employee. Sent in the SuperChoice member payload to help the fund match contributions.

employmentPayrollNumber

string

Employment / payroll number used by the employer to identify this employee in payroll systems. Passed through as employmentPayrollNumber to SuperChoice.

abn

string

Australian Business Number (ABN) for the employee (typically contractors). Stored for reference only and not sent to SuperChoice APIs.

createdAt

string

Created timestamp

updatedAt

string

Updated timestamp

400

Bad request - Invalid employee data or duplicate email

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes. Common codes: 4030 (Employer not found), 4031 (Invalid ABN), 4040 (Fund not found).

401

Unauthorized - Invalid authentication credentials

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes. Common codes: 4030 (Employer not found), 4031 (Invalid ABN), 4040 (Fund not found).

Sample Request - cURL

curl 'https://super.mygigsters.com.au/v1/employees' -X POST \
    -u "apiUsername:apiPassword-from-api-keys"  \
    -H "Content-Type: application/json" --data '{"email":"lisa.black@email.com","name":{"firstName":"Lisa","lastName":"Brown"},"gender":"FEMALE","dob":{"year":1988,"month":"DECEMBER","day":13},"address":{"australianAddress":{"line1":"640 Gordon Street","line2":" ","line3":" ","line4":" ","suburb":"MANLY VALE","postCode":"2093","stateOrTerritory":"NSW","countryCode":"AU"}},"taxFileNumber":"182134556","usi":"BTA0287AU","memberNumber":"MEM1001","employmentPayrollNumber":"EMP-000123","abn":"34623710896"}'

Sample Response - 201

{
  "employeeId": "6953884140b85eeded2bf2ea",
  "email": "lisa.black@email.com",
  "name": {
    "firstName": "Lisa",
    "lastName": "Brown"
  },
  "gender": "FEMALE",
  "dob": {
    "year": 1988,
    "month": "DECEMBER",
    "day": 13
  },
  "address": {
    "australianAddress": {
      "line1": "640 Gordon Street",
      "line2": " ",
      "line3": " ",
      "line4": " ",
      "suburb": "MANLY VALE",
      "postCode": "2093",
      "stateOrTerritory": "NSW",
      "countryCode": "AU"
    }
  },
  "taxFileNumber": "182134556",
  "abn": "34623710896",
  "usi": "BTA0287AU",
  "memberNumber": "MEM1001",
  "employmentPayrollNumber": "EMP-000123",
  "employerId": "6944f5bc514fc0a1479bffdb",
  "createdAt": "2025-12-30T08:07:29.894Z",
  "updatedAt": "2025-12-30T08:07:29.894Z"
}

List All Employees

GET/v1/employees

Overview

Retrieves all employees associated with the authenticated employer. Returns a paginated list of employee records with their static information.

Pagination

This endpoint supports pagination to efficiently retrieve large employee lists. Use the page and limit query parameters to control the results.

page: Page number (default: 1)
limit: Number of items per page (default: 10, maximum: 100)

Use Case

Display list of employees in UI with pagination
Select employees for contribution submission
Verify which employees are onboarded
Efficiently browse through large employee databases

Request Parameters

Parameter	Type	Description
page	integer	Page number for pagination (default: 1)
limit	integer	Number of items per page (default: 10, max: 100)

Responses

Content-Type: application/json

Response Code

Description

Schema

200

List of employees retrieved successfully

Parameter	Type	Description
employees	array	List of employees. Each employee object matches the Employee response model from `GET /v1/employees/{id}` and may include optional superannuation identifiers (usi, memberNumber, employmentPayrollNumber, abn).
total	number	Total count of employees across all pages
totalPages	number	Total number of pages available
hasNext	boolean	Whether there is a next page available
hasPrevious	boolean	Whether there is a previous page available

401

Unauthorized - Invalid authentication credentials

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes. Common codes: 4030 (Employer not found), 4031 (Invalid ABN), 4040 (Fund not found).

Sample Request - cURL

curl 'https://super.mygigsters.com.au/v1/employees' \
    -u "apiUsername:apiPassword-from-api-keys"

Sample Response - 200

{
  "employees": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "lisa.brown@email.com",
      "name": {
        "firstName": "Lisa",
        "lastName": "Brown"
      },
      "gender": "FEMALE",
      "dob": {
        "year": 1988,
        "month": "MAY",
        "day": 13
      },
      "address": {
        "australianAddress": {
          "line1": "640 Gordon Street",
          "line2": " ",
          "line3": " ",
          "line4": " ",
          "suburb": "MANLY VALE",
          "postCode": "2093",
          "stateOrTerritory": "NSW",
          "countryCode": "AU"
        }
      },
      "taxFileNumber": "182134556",
      "employerId": "employer_123",
      "usi": "BTA0287AU",
      "memberNumber": "MEM1001",
      "employmentPayrollNumber": "EMP-000123",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 45,
  "totalPages": 5,
  "hasNext": true,
  "hasPrevious": false
}

Get Employee by ID

GET/v1/employees/{id}

Overview

Retrieves employee information by UUID. Returns all static employee data stored in the database.

Use Case

Verify employee information before submitting contributions
Retrieve employee details for display in UI
Validate employee exists before contribution submission

Request Parameters

Parameter	Type	Description
employeeId *	string	Employee ID

Responses

Content-Type: application/json

Response Code

Description

Schema

200

Employee retrieved successfully

Parameter

Type

Description

string

Employee ID

string

Employee email address (optional)

name

object

Employee name

Parameter	Type	Description
firstName	string	First or given name of the fund member as registered with their superannuation fund. Must match the name on the member's fund account for successful contribution allocation.
lastName	string	Last name or surname of the fund member as registered with their superannuation fund. Must match exactly for the contribution to be successfully allocated.

gender

string

Employee gender. Valid values: NOT_STATED, MALE, FEMALE, INDETERMINATE

dob

object

Date of birth

Parameter	Type	Description
year	number	Birth year (4 digits). Used along with month and day to verify member identity with the fund. Members must be at least 15 years old to receive superannuation contributions.
month	string	Birth month as a full month name (uppercase). Must match the member's date of birth registered with their fund.
day	number	Birth day of the month (1-31). Ensure this matches the fund's records for successful member identification.

address

object

Employee address

Parameter	Type	Description
australianAddress	object	Australian residential address of the fund member. Used for member identification and correspondence if needed.

taxFileNumber

string

Tax File Number (TFN)

employerId

string

Employer ID this employee belongs to

usi

string

Unique Superannuation Identifier (USI) for the employee’s chosen super fund/product. Used when building validation and submission payloads to SuperChoice.

memberNumber

string

Member number issued by the superannuation fund for this employee. Sent in the SuperChoice member payload to help the fund match contributions.

employmentPayrollNumber

string

Employment / payroll number used by the employer to identify this employee in payroll systems. Passed through as employmentPayrollNumber to SuperChoice.

abn

string

Australian Business Number (ABN) for the employee (typically contractors). Stored for reference only and not sent to SuperChoice APIs.

createdAt

string

Created timestamp

updatedAt

string

Updated timestamp

401

Unauthorized - Invalid authentication credentials

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes. Common codes: 4030 (Employer not found), 4031 (Invalid ABN), 4040 (Fund not found).

404

Employee not found

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes. Common codes: 4030 (Employer not found), 4031 (Invalid ABN), 4040 (Fund not found).

Sample Request - cURL

curl 'https://super.mygigsters.com.au/v1/employees/{id}' \
    -u "apiUsername:apiPassword-from-api-keys"

Sample Response - 200

{
  "id": "6953947795fa599416406fc6",
  "email": "lisa.purple@email.com",
  "name": {
    "firstName": "Lisa",
    "lastName": "Brown"
  },
  "gender": "FEMALE",
  "dob": {
    "year": 1988,
    "month": "DECEMBER",
    "day": 13
  },
  "address": {
    "australianAddress": {
      "line1": "640 Gordon Street",
      "line2": " ",
      "line3": " ",
      "line4": " ",
      "suburb": "MANLY VALE",
      "postCode": "2093",
      "stateOrTerritory": "NSW",
      "countryCode": "AU"
    }
  },
  "taxFileNumber": "182134556",
  "abn": "34623710896",
  "usi": "BTA0287AU",
  "memberNumber": "MEM1001",
  "employmentPayrollNumber": "EMP-000123",
  "employerId": "6944f5bc514fc0a1479bffdb",
  "createdAt": "2025-12-30T08:59:35.138Z",
  "updatedAt": "2025-12-30T08:59:35.138Z"
}

Update Employee

PUT/v1/employees/{id}

Overview

Updates an existing employee record. Only the fields provided in the request body will be updated. All other fields will remain unchanged.

Update Behavior

All fields in the request body are optional
Only provided fields will be updated
Email uniqueness is validated - cannot update to an email that already exists for another employee
Employee must belong to the authenticated employer

Use Case

Update employee super fund details (USI, member number)
Change employee address or contact information
Update employee name or personal details
Modify employment/payroll number

Request Parameters

Parameter	Type	Description
employeeId *	string	Employee ID

Request Body

Required: Yes

Content-Type: application/json

Parameter

Type

Description

string

Employee email address (must be valid email format)

name

object

Employee name

Parameter	Type	Description
firstName	string	First or given name of the fund member as registered with their superannuation fund. Must match the name on the member's fund account for successful contribution allocation.
lastName	string	Last name or surname of the fund member as registered with their superannuation fund. Must match exactly for the contribution to be successfully allocated.

gender

string (NOT_STATED, MALE, FEMALE, INDETERMINATE)

Employee gender. Valid values: NOT_STATED, MALE, FEMALE, INDETERMINATE

dob

object

Date of birth

Parameter	Type	Description
year	number	Birth year (4 digits). Used along with month and day to verify member identity with the fund. Members must be at least 15 years old to receive superannuation contributions.
month	string (JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER)	Birth month as a full month name (uppercase). Must match the member's date of birth registered with their fund.
day	number	Birth day of the month (1-31). Ensure this matches the fund's records for successful member identification.

address

object

Employee address

Parameter

Type

Description

australianAddress

object

Australian residential address of the fund member. Used for member identification and correspondence if needed.

Parameter	Type	Description
line1	string	Primary address line - typically street number and street name. Example: "640 Gordon Street" or "Unit 5, 123 Main Road"
line2	string	Secondary address line - additional address information if needed (e.g., building name, floor). Use a single space " " if not applicable.
line3	string	Tertiary address line - rarely used, for complex addresses. Use a single space " " if not applicable.
line4	string	Quaternary address line - very rarely used. Use a single space " " if not applicable.
suburb	string	Suburb or locality name. Must be a valid Australian suburb name. Use uppercase for consistency with Australia Post standards.
postCode	string	Australian postcode - a 4-digit number identifying the postal delivery area. Must be a valid Australian postcode.
stateOrTerritory	string (NSW, VIC, QLD, SA, WA, TAS, NT, ACT)	Australian state or territory abbreviation. Valid values: NSW, VIC, QLD, SA, WA, TAS, NT, ACT
countryCode	string (AU)	ISO 3166-1 alpha-2 country code. Must be "AU" for Australian addresses. International addresses are not currently supported.

taxFileNumber

string

Tax File Number (TFN)

usi

string

Unique Superannuation Identifier (USI) for the employee's chosen super fund/product. This will be used when building validation and submission payloads to SuperChoice.

memberNumber

string

Member number issued by the superannuation fund for this employee. This will be sent in the SuperChoice member payload and used by the fund to directly match contributions to the member's account.

employmentPayrollNumber

string

Employment / payroll number used by the employer to identify this employee in payroll systems. This will be sent as the employmentPayrollNumber field to SuperChoice.

abn

string

Australian Business Number (ABN) for the employee (typically contractors). Stored for reference only and **not** sent to SuperChoice APIs.

Responses

Content-Type: application/json

Response Code

Description

Schema

200

Employee updated successfully

Parameter

Type

Description

employeeId

string

Employee ID

string

Employee email address (optional)

name

object

Employee name

Parameter	Type	Description
firstName	string	First or given name of the fund member as registered with their superannuation fund. Must match the name on the member's fund account for successful contribution allocation.
lastName	string	Last name or surname of the fund member as registered with their superannuation fund. Must match exactly for the contribution to be successfully allocated.

gender

string

Employee gender. Valid values: NOT_STATED, MALE, FEMALE, INDETERMINATE

dob

object

Date of birth

Parameter	Type	Description
year	number	Birth year (4 digits). Used along with month and day to verify member identity with the fund. Members must be at least 15 years old to receive superannuation contributions.
month	string	Birth month as a full month name (uppercase). Must match the member's date of birth registered with their fund.
day	number	Birth day of the month (1-31). Ensure this matches the fund's records for successful member identification.

address

object

Employee address

Parameter	Type	Description
australianAddress	object	Australian residential address of the fund member. Used for member identification and correspondence if needed.

taxFileNumber

string

Tax File Number (TFN)

employerId

string

Employer ID this employee belongs to

usi

string

Unique Superannuation Identifier (USI) for the employee's chosen super fund/product. Used when building validation and submission payloads to SuperChoice.

memberNumber

string

Member number issued by the superannuation fund for this employee. Sent in the SuperChoice member payload to help the fund match contributions.

employmentPayrollNumber

string

Employment / payroll number used by the employer to identify this employee in payroll systems. Passed through as employmentPayrollNumber to SuperChoice.

abn

string

Australian Business Number (ABN) for the employee (typically contractors). Stored for reference only and not sent to SuperChoice APIs.

createdAt

string

Created timestamp

updatedAt

string

Updated timestamp

400

Bad request - Invalid employee data or duplicate email

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes.

401

Unauthorized - Invalid authentication credentials

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes.

404

Employee not found

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes.

Sample Request - cURL

curl 'https://super.mygigsters.com.au/v1/employees/{id}' -X PUT \
    -u "apiUsername:apiPassword-from-api-keys"  \
    -H "Content-Type: application/json" --data '{"usi":"BTA0287AU","memberNumber":"MEM1001","employmentPayrollNumber":"EMP-000124"}'

Sample Response - 200

{
  "employeeId": "69536c2640b85eeded2bf2e9",
  "email": "lisa.brown@email.com",
  "name": {
    "firstName": "Lisa",
    "lastName": "Brown"
  },
  "gender": "FEMALE",
  "dob": {
    "year": 1988,
    "month": "MAY",
    "day": 13
  },
  "address": {
    "australianAddress": {
      "line1": "640 Gordon Street",
      "line2": " ",
      "line3": " ",
      "line4": " ",
      "suburb": "MANLY VALE",
      "postCode": "2093",
      "stateOrTerritory": "NSW",
      "countryCode": "AU"
    }
  },
  "taxFileNumber": "182134556",
  "employerId": "6944f5bc514fc0a1479bffdb",
  "usi": "BTA0287AU",
  "memberNumber": "MEM1001",
  "employmentPayrollNumber": "EMP-000124",
  "createdAt": "2025-12-19T07:18:39.442Z",
  "updatedAt": "2025-12-19T10:30:00.000Z"
}

Search Employees

GET/v1/employees/search

Overview

Searches for employees by various attributes such as USI, email, name, member number, etc. You can search by one or multiple attributes. All provided search criteria are combined with AND logic.

Note: At least one search parameter must be provided. If no search parameters are provided, an empty array is returned.

Search Parameters

usi: Search by Unique Superannuation Identifier (exact match)
email: Search by email address (partial match, case-insensitive)
firstName: Search by first name (partial match, case-insensitive)
lastName: Search by last name (partial match, case-insensitive)
memberNumber: Search by member number (exact match)
employmentPayrollNumber: Search by employment/payroll number (exact match)

Use Case

Find employee by USI when you only have super fund information
Search by name when you don't know the employee ID
Find employee by email address
Locate employee by payroll number

Request Parameters

Parameter	Type	Description
usi	string	Search by Unique Superannuation Identifier (exact match)
email	string	Search by email address (partial match, case-insensitive)
firstName	string	Search by first name (partial match, case-insensitive)
lastName	string	Search by last name (partial match, case-insensitive)
memberNumber	string	Search by member number (exact match)
employmentPayrollNumber	string	Search by employment/payroll number (exact match)

Responses

Content-Type: application/json

Response Code

Description

Schema

200

Search results retrieved successfully

Parameter	Type	Description
employees	array	List of employees matching the search criteria. Each employee object matches the Employee response model from `GET /v1/employees/{employeeId}`.
total	number	Total count of employees matching the search criteria

400

Bad request - No search parameters provided or invalid parameters

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes.

401

Unauthorized - Invalid authentication credentials

Parameter	Type	Description
success	boolean	Always false for error responses, indicating the operation did not succeed.
statusCode	integer	HTTP status code indicating the type of error. Common values: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Server Error)
message	string	Human-readable error message explaining what went wrong. May include specific details about which field or value caused the error.
errorCode	integer	SuperChoice-specific error code for programmatic error handling. Refer to the error code reference documentation for a complete list of codes.

Sample Request - cURL

curl 'https://super.mygigsters.com.au/v1/employees/search?usi=40328908469310&email=lisa.brown%40email.com&firstName=Lisa&lastName=Brown&memberNumber=MEM1001&employmentPayrollNumber=EMP-000123' \
    -u "apiUsername:apiPassword-from-api-keys"

Sample Response - 200

{
  "employees": [
    {
      "employeeId": "6944fc4fa11ab4199bf0df2d",
      "email": "lisa.brown@email.com",
      "name": {
        "firstName": "Lisa",
        "lastName": "Brown"
      },
      "gender": "FEMALE",
      "dob": {
        "year": 1988,
        "month": "MAY",
        "day": 13
      },
      "address": {
        "australianAddress": {
          "line1": "640 Gordon Street",
          "line2": " ",
          "line3": " ",
          "line4": " ",
          "suburb": "MANLY VALE",
          "postCode": "2093",
          "stateOrTerritory": "NSW",
          "countryCode": "AU"
        }
      },
      "taxFileNumber": "182134556",
      "employerId": "6944f5bc514fc0a1479bffdb",
      "createdAt": "2025-12-19T07:18:39.442Z",
      "updatedAt": "2025-12-19T07:18:39.442Z"
    }
  ],
  "total": 1
}