Skip to content

Tātou integration overview ​

See API integration authentication and planning for the cross-integration view of how this token is obtained and whether advance planning is needed.

note

Each job may have only one active Tātou integration. Disabled integrations do not count as active. If you need help setting up integrations, see Setting up integrations.

Uniqueness detection ​

PICMI only checks for duplicates based on email, not Staff ID. This means that if an employee’s email is different, PICMI will assume they are a new hire, even if they are actually the same person in Tātou.

Configuration settings ​

These settings are configured on the Tātou integration. A job is then assigned to the relevant integration, so different jobs can use different Tātou earning rules and settings.

ConfigurationDescriptionValues
Security tokenToken used to connect PICMI to TātouText (required)
Contract typeContract type applied when an employee is createdCasual
Earning ruleEarning rule applied when an employee is createdTātou earning rules
RoleRole applied when an employee is createdTātou roles
Employee status on creationEmployee status applied when an employee is createdTātou employee statuses
Top up to hourly rateIntegration-level fallback for whether Tātou tops earnings up to the agreed hourly rateOptional
Weekly minimum earningsIntegration-level fallback for the minimum agreed weekly earnings sent to TātouOptional; currency

Top up to hourly rate ​

Top up to hourly rate controls whether Tātou tops the person's earnings up to the agreed hourly rate. The setting has three choices:

ChoiceMeaning
InheritUse the setting from the parent level.
YesExplicitly top up earnings to the agreed hourly rate.
NoExplicitly do not top up earnings to the agreed hourly rate.

The inheritance order is:

  1. The Tātou integration setting provides the organisation-wide default.
  2. The job setting can inherit the integration setting or override it.
  3. A personal applicant override can inherit the job setting or explicitly override it.

Inherit is different from No. Inherit delegates the decision to the parent level. No is an explicit instruction not to top up. Selecting No at any level stops inheritance and disables top-up for that level and any more specific level that is set to Inherit.

note

Warning: Selecting No at the integration, job, or personal override level explicitly disables top-up at that level. More specific settings set to Inherit will continue that No value.

For example:

  • Integration: Yes → job: Inherit → applicant: Inherit = top up (Yes flows through both levels).
  • Integration: Yes → job: No → applicant: Inherit = do not top up (No stops inheritance at the job).
  • Integration: Yes → job: Inherit → applicant: No = do not top up for that applicant only.

Use the integration setting when the same rule applies to multiple jobs. Set the final contractual requirement on the job, because the job details are used for the employment contract. Use a personal override only when an individual applicant has an agreed exception. If a personal override is set to Inherit, the applicant follows the job setting; if a job is set to Inherit, it follows the Tātou integration setting.

The job settings provide job-level values for these fields. You can set values for an individual through personal overrides. Tātou uses the most specific value available, in this order:

  1. Personal override
  2. Job setting
  3. Tātou integration setting

The selected values are used when Tātou creates or updates the employee's employment details.

Usage ​

Separate Tātou integrations when business requirements call for different earning rules, roles, contract types, pay arrangements, or worker groups. Assign each job to the integration with the appropriate settings. For example:

  • RSE – First/Second Year job → Tātou – RSE First/Second Year integration
  • RSE – Third Year+ job → Tātou – RSE Third Year+ integration

The RSE scheme is one example only. Other organisations may need separate integrations for different Tātou earning rules, roles, contract types, pay arrangements, or worker groups.

RSE example ​

RSE workers in their first and second seasons must be paid at least the applicable adult minimum wage. Workers returning for their third or subsequent RSE seasons must be paid at least the minimum wage plus 10%. These requirements may require separate Tātou earning rules and integrations for first/second-season and third-or-later-season workers.

As at late 2026, the RSE instructions in force from 1 April 2026 describe these requirements in Immigration New Zealand's authoritative guidance, and the adult minimum wage is $23.95 per hour from 1 April 2026 according to Employment New Zealand. Minimum wage rates are reviewed annually, so check the current guidance before configuring an earning rule.

For example, weekly minimum earnings can be calculated from an agreed hourly rate and weekly hours:

  • $25/hour × 30 hours = $750 weekly minimum earnings
  • $27.50/hour × 30 hours = $825 weekly minimum earnings

These are calculation examples only. weekly_min_earnings can be configured at the integration, job, or personal override level. The most specific value available is applied to the employee's employment details.

PICMI-Tātou integration fields ​

Field NameDescriptionValidation/Constraint/Default ValueSource
IDUnique identifierIntegration Configuration
First namesGiven name(s) of the individual.Personal Information
SurnameFamily name of the individual.Personal Information
EmailEmail address of the individual.Personal Information
BirthdateDate of birth of the individual.Personal Information
NationalityNationality of the individual.Personal Information
Next hourly rateThe remuneration rate for the individual.Job
Effective fromStart date for the next hourly rate to take effect.Plus one dayJob
Job titleTitle of the individual’s position.Job
Start dateStart date of employment or contract.Job
Recruitment typeType of recruitment for the individual.Default (NZ Employee)Integration Configuration
Contract typeType of contract under which the individual is employed.Integration Configuration
Primary rolePrimary role of the individual in the organisation.Integration Configuration
StatusEmployment status of the individual (e.g., active, inactive).InactiveIntegration Configuration

FAQ ​

How can I view the staff ID?

+

Duplicate Tātou integration error

+

General troubleshooting ​

PICMI is the simple hiring tool that helps make your job their first choice