ID Batch V2

Endpoint for processing batch user registrations (FanID) and their related data.

📥 Postman Collection

URLs

Method	URL	Action	Description
POST	`/api/v2/IF_ID_Batch`	Register	Process batch user registrations and their data

Production:

{connect-production}/api/v2/IF_ID_Batch

Staging:

{connect-staging}/api/v2/IF_ID_Batch

Authentication

All requests require an access token obtained from the Security endpoint. The token must be sent in the AccessToken header.

AccessToken: {your_token}

Process Batch Registrations

Request

Endpoint: POST {connect-production}/api/v2/IF_ID_Batch

Headers:

AccessToken: {access_token}
Content-Type: application/json

Body Structure

Main Structure

json

{
  "systemId": 0,
  "data": [
    {
      "data": { ... },
      "numbers": [ ... ],
      "sysValues": [ ... ],
      "addresses": { ... },
      "transactions": [ ... ],
      "memberships": [ ... ],
      "optins": [ ... ],
      "attributes": [ ... ],
      "pwd": "string",
      "pwdhash": "string"
    }
  ]
}

Field	Type	Required	Description
`systemId`	number	Yes	Source system ID (provided by Fanbase)
`data`	array	Yes	Array of objects with user data

`data` Object Fields (Personal Data)

json

{
  "data": {
    "identity": 0,
    "name1": "string",
    "gender": "string",
    "socialName": "string",
    "birthday": 0,
    "birthMonth": 0,
    "birthYear": 0,
    "nationalityIso3": "string"
  }
}

Field	Type	Required	Description
`identity`	number	Yes	Always keep 0 for integration
`name1`	string	Yes	Full name
`gender`	string	No	Gender: `M` / `F` / `O` / `null`
`socialName`	string	No	Nickname/Social name
`birthday`	number	Yes	Birth day (01-31)
`birthMonth`	number	Yes	Birth month (01-12)
`birthYear`	number	Yes	Birth year (4 digits)
`nationalityIso3`	string	No	Nationality, ISO3 format (e.g.: BRA)

`numbers` Array Fields (Documents)

json

{
  "numbers": [
    {
      "numberType": 0,
      "number": "string",
      "verified": 0
    }
  ]
}

Field	Type	Required	Description
`numberType`	number	Yes	Document type (see table below)
`number`	string	Yes	Document number (unformatted)
`verified`	number	No	Verified: `0` (no) or `1` (yes)

Document Types (numberType)

Code	Type
`1`	CPF (Brazilian Tax ID)
`3`	Phone
`4`	Email

`sysValues` Array Fields (System Values)

Relevant data not directly linked to the registration (e.g.: Membership card number, Member code).

json

{
  "sysValues": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Field	Type	Required	Description
`key`	string	Yes	Identifier key
`value`	string	Yes	Associated value

`addresses` Object Fields (Address)

json

{
  "addresses": {
    "addressType": 0,
    "add1": "string",
    "add2": "string",
    "number": 0,
    "add3": "string",
    "zip": "string",
    "city": "string",
    "state": "string",
    "iso3": "string"
  }
}

Field	Type	Required	Description
`addressType`	number	Yes	Type: `1` (Primary), `2` (Alternative)
`add1`	string	Yes	Street/Address
`add2`	string	No	Complement
`number`	number	No	House number
`add3`	string	Yes	Neighborhood
`zip`	string	Yes	Postal code
`city`	string	Yes	City
`state`	string	Yes	State (2 digits: SP/DF/RJ/etc)
`iso3`	string	Yes	Country, ISO3 format (e.g.: BRA)

`transactions` Array Fields (Transactions) - Optional

Optional class to add transaction data (e-commerce purchases, stores, etc).

json

{
  "transactions": [
    {
      "date": "2025-09-20T18:41:31.219Z",
      "type": 0,
      "productType": 0,
      "productDesc": "string",
      "productExternalCode": "string",
      "qty": 0,
      "value": 0,
      "channel": "string",
      "externalCode": "string",
      "deliveryMode": "string",
      "priceType": "string",
      "cupon": "string",
      "paymentMode": "string",
      "complement": "string",
      "discount": "string",
      "discountValue": 0
    }
  ]
}

Field	Type	Required	Description
`date`	datetime	Yes	Transaction date (ISO 8601)
`type`	number	Yes	Transaction type
`productType`	number	Yes	Product type
`productDesc`	string	Yes	Product description
`productExternalCode`	string	Yes	Product code in source system
`qty`	number	Yes	Quantity
`value`	number	Yes	Unit value
`channel`	string	Yes	Sales channel (e.g.: Store name)
`externalCode`	string	Yes	Transaction code in source system
`deliveryMode`	string	No	Delivery mode
`priceType`	string	No	Price type
`cupon`	string	No	Discount coupon code
`paymentMode`	string	Yes	Payment mode (Credit card, Pix, etc)
`complement`	string	No	Item code in order (e.g.: item:1, item:2)
`discount`	string	No	Discount reason
`discountValue`	number	No	Discount value

`memberships` Array Fields (Membership Plans) - Optional

Optional class to add membership plan data.

json

{
  "memberships": [
    {
      "externalId": "string",
      "status": "string",
      "data": "2025-09-20T18:41:31.219Z",
      "cancelamento": "2025-09-20T18:41:31.219Z",
      "codigoCliente": "string",
      "plano": "string",
      "planoCode": "string",
      "complemento": "string",
      "parcelas": 0,
      "validade": "2025-09-20T18:41:31.219Z",
      "origem": "string",
      "ativacao": "2025-09-20T18:41:31.219Z",
      "tipoVigencia": "string",
      "formaPagamento": "string",
      "guests": [ ... ],
      "attributes": [ ... ]
    }
  ]
}

Field	Type	Required	Description
`externalId`	string	Yes	Contract code in source system
`status`	string	Yes	Status: Active/Inactive/Delinquent/etc
`data`	datetime	Yes	Contract date
`cancelamento`	datetime	No	Cancellation date (if cancelled)
`codigoCliente`	string	Yes	Customer CPF or Email
`plano`	string	Yes	Plan name
`planoCode`	string	No	Plan code in source system
`complemento`	string	No	Other contract information
`parcelas`	number	No	Number of paid installments
`validade`	datetime	No	Expiration date (when no auto-renewal)
`origem`	string	No	Contract origin channel
`ativacao`	datetime	No	Activation date (start of validity)
`tipoVigencia`	string	No	Validity type: Annual, Monthly
`formaPagamento`	string	No	Payment mode (Credit card, Pix, etc)

Dependents/Guests (`guests`)

json

{
  "guests": [
    {
      "guestFanbaseId": 0,
      "externalId": "string",
      "cpf": "string",
      "email": "string",
      "celular": "string",
      "name1": "string",
      "gender": "string",
      "socialName": "string",
      "birthday": 0,
      "birthMonth": 0,
      "birthYear": 0
    }
  ]
}

Field	Type	Required	Description
`guestFanbaseId`	number	No	Existing Fanbase ID (if known)
`externalId`	string	No	Dependent code in source system
`cpf`	string	No	Dependent's CPF
`email`	string	No	Dependent's email
`celular`	string	No	Dependent's phone
`name1`	string	No	Full name
`gender`	string	No	Gender: M/F/O/null
`socialName`	string	No	Nickname
`birthday`	number	No	Birth day (01-31)
`birthMonth`	number	No	Birth month (01-12)
`birthYear`	number	No	Birth year (4 digits)

Membership Attributes (`attributes`)

json

{
  "attributes": [
    {
      "type": "string",
      "name": "string",
      "value": "string",
      "note": "string",
      "externalCode": "string"
    }
  ]
}

Field	Type	Required	Description
`type`	string	Yes	Attribute type (e.g.: Card)
`name`	string	No	Identification name (e.g.: Membership card)
`value`	string	Yes	Attribute value
`note`	string	No	Free field for notes
`externalCode`	string	No	Internal attribute code

`optins` Array Fields (Opt-ins)

Opt-in information (GDPR/LGPD) granted by the fan in legacy systems.

json

{
  "optins": [
    {
      "optinCode": "string",
      "optinDesc": "string",
      "optinDate": "2025-09-20T18:41:31.219Z",
      "optinCancelDate": "2025-09-20T18:41:31.219Z"
    }
  ]
}

Field	Type	Required	Description
`optinCode`	string	Yes	Opt-in code (e.g.: PRIVACYUSE)
`optinDesc`	string	Yes	Opt-in description
`optinDate`	datetime	Yes	Acceptance date and time
`optinCancelDate`	datetime	No	Cancellation date and time

`attributes` Array Fields (User Attributes)

Custom fan attributes for customized display in Fanbox.

Attention

You need to internally request attribute configuration before using.

json

{
  "attributes": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Field	Type	Required	Description
`key`	string	Yes	Attribute identification key
`value`	string	Yes	Attribute value

Password Fields (SSO Account Creation)

SSO Account Creation

If you send the pwd or pwdhash field, the system will automatically create an SSO (Single Sign-On) account for the user. This allows the user to log into the platform using their credentials.

Field	Type	Required	Description
`pwd`	string	No	Password in plain text for account creation
`pwdhash`	string	No	Encrypted password for account creation

Important

Use pwd to send plain text password (the system will hash it)
Use pwdhash if you already have the password in hash format
Never send both - choose one or the other
If neither is sent, the user will be created without a login account

Complete Example - Simple Registration

json

{
  "systemId": 0,
  "data": [
    {
      "data": {
        "identity": 0,
        "name1": "John Smith",
        "gender": "M",
        "socialName": "John",
        "birthday": 15,
        "birthMonth": 8,
        "birthYear": 1990,
        "nationalityIso3": "BRA"
      },
      "numbers": [
        {
          "numberType": 1,
          "number": "12345678900",
          "verified": 1
        },
        {
          "numberType": 4,
          "number": "john@example.com",
          "verified": 1
        }
      ],
      "sysValues": [
        {
          "key": "MEMBER_CODE",
          "value": "MEM-123456"
        }
      ],
      "addresses": {
        "addressType": 1,
        "add1": "Example Street",
        "add2": "Apt 101",
        "number": 123,
        "add3": "Downtown",
        "zip": "01234567",
        "city": "São Paulo",
        "state": "SP",
        "iso3": "BRA"
      }
    }
  ]
}

Complete Example - Registration with Membership Plan and SSO Account

json

{
  "systemId": 0,
  "data": [
    {
      "data": {
        "identity": 0,
        "name1": "Mary Johnson",
        "gender": "F",
        "birthday": 20,
        "birthMonth": 3,
        "birthYear": 1985,
        "nationalityIso3": "BRA"
      },
      "numbers": [
        {
          "numberType": 1,
          "number": "98765432100",
          "verified": 1
        },
        {
          "numberType": 4,
          "number": "mary@example.com",
          "verified": 1
        }
      ],
      "addresses": {
        "addressType": 1,
        "add1": "Main Avenue",
        "number": 500,
        "add3": "Garden District",
        "zip": "04567890",
        "city": "São Paulo",
        "state": "SP",
        "iso3": "BRA"
      },
      "memberships": [
        {
          "externalId": "CONTRACT-2025-001",
          "status": "Active",
          "data": "2025-01-15T10:00:00.000Z",
          "codigoCliente": "98765432100",
          "plano": "Annual Premium Plan",
          "planoCode": "PREMIUM-ANNUAL",
          "parcelas": 12,
          "validade": "2026-01-15T10:00:00.000Z",
          "origem": "Website",
          "ativacao": "2025-01-15T10:00:00.000Z",
          "tipoVigencia": "Annual",
          "formaPagamento": "Credit Card"
        }
      ],
      "optins": [
        {
          "optinCode": "NEWSLETTER",
          "optinDesc": "I agree to receive newsletters",
          "optinDate": "2025-01-15T10:00:00.000Z"
        },
        {
          "optinCode": "SMS",
          "optinDesc": "I agree to receive promotional SMS",
          "optinDate": "2025-01-15T10:00:00.000Z"
        }
      ],
      "pwd": "password123"
    }
  ]
}

Success Response

Status: 200 OK

json

{
  "header": {
    "codigo": 1,
    "msg": "Ok"
  },
  "data": {
    "resume": {
      "total": 1,
      "success": 1,
      "fail": 0,
      "status": "SUCCESS"
    },
    "items": [
      {
        "userId": 6011883,
        "success": true,
        "cpf": "12345678900",
        "email": "john@example.com",
        "alternativeNumber": null,
        "messageError": null,
        "account": {
          "success": true,
          "login": "12345678900",
          "messageError": null
        }
      }
    ]
  }
}

Response Fields

Resume

Field	Type	Description
`total`	number	Total users processed
`success`	number	Total processed successfully
`fail`	number	Total with error
`status`	string	Overall status: `SUCCESS`, `PARTIAL_SUCCESS` or `FAILURE`

Items

Field	Type	Description
`userId`	number	Created user ID (0 if not created)
`success`	boolean	Processing success
`cpf`	string	User's CPF
`email`	string	User's email
`alternativeNumber`	string/null	Alternative code
`messageError`	string/null	Error message
`account`	object	Created SSO account details

Account (when `pwd` or `pwdhash` is sent)

Field	Type	Description
`success`	boolean	If the SSO account was created successfully
`login`	string	Account login (usually CPF)
`messageError`	string/null	Account creation error message

Implementation Example

javascript

async function processBatchRegistrations(data, accessToken) {
  const response = await fetch('{connect-production}/api/v2/IF_ID_Batch', {
    method: 'POST',
    headers: {
      'AccessToken': accessToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    throw new Error(`Error ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

const data = {
  systemId: 0,
  data: [
    {
      data: {
        identity: 0,
        name1: "John Smith",
        birthday: 15,
        birthMonth: 8,
        birthYear: 1990
      },
      numbers: [
        { numberType: 1, number: "12345678900", verified: 1 },
        { numberType: 4, number: "john@example.com", verified: 1 }
      ],
      pwd: "password123"
    }
  ]
};

processBatchRegistrations(data, accessToken)
  .then(result => console.log(result))
  .catch(error => console.error(error));

Auxiliary Tables

For fields like iso3 (country) and nationalityIso3 (nationality), see the Auxiliary Tables page with the complete list of country ISO3 codes.

ID Batch V2 ​

URLs ​

Authentication ​

Process Batch Registrations ​

Request ​

Body Structure ​

Main Structure ​

data Object Fields (Personal Data) ​

numbers Array Fields (Documents) ​

Document Types (numberType) ​

sysValues Array Fields (System Values) ​

addresses Object Fields (Address) ​

transactions Array Fields (Transactions) - Optional ​

memberships Array Fields (Membership Plans) - Optional ​

Dependents/Guests (guests) ​

Membership Attributes (attributes) ​

optins Array Fields (Opt-ins) ​

attributes Array Fields (User Attributes) ​

Password Fields (SSO Account Creation) ​

Complete Example - Simple Registration ​

Complete Example - Registration with Membership Plan and SSO Account ​

Success Response ​

Response Fields ​

Resume ​

Items ​

Account (when pwd or pwdhash is sent) ​

Implementation Example ​

Auxiliary Tables ​

ID Batch V2

URLs

Authentication

Process Batch Registrations

Request

Body Structure

Main Structure

`data` Object Fields (Personal Data)

`numbers` Array Fields (Documents)

Document Types (numberType)

`sysValues` Array Fields (System Values)

`addresses` Object Fields (Address)

`transactions` Array Fields (Transactions) - Optional

`memberships` Array Fields (Membership Plans) - Optional

Dependents/Guests (`guests`)

Membership Attributes (`attributes`)

`optins` Array Fields (Opt-ins)

`attributes` Array Fields (User Attributes)

Password Fields (SSO Account Creation)

Complete Example - Simple Registration

Complete Example - Registration with Membership Plan and SSO Account

Success Response

Response Fields

Resume

Items

Account (when `pwd` or `pwdhash` is sent)

Implementation Example

Auxiliary Tables