Submit a membership request for a person (server-side)

POST

/v1/enroll

const url = 'https://api.vimine.network/v1/enroll';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"email":"hello@example.com","first_name":"example","last_name":"example","codicefiscale":"example","codicefiscale_confirmed":true,"guardian":{"first_name":"example","last_name":"example","relation":"example","codicefiscale":"example","email":"hello@example.com","phone":"example"},"address":{"kind":"residence","line":"example","postal_code":"example","city":"example","province":"example","country":"IT"},"phone":"example","dob":"2026-04-15","gender":"M","birthplace":"example","birth_country":"example","membership_type":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","locale":"example","accept_statuto":{"version":1,"sha256":"example"},"privacy_notice":{"version":1,"sha256":"example","locale":"example"},"accept_terms":{"version":"example","sha256":"example"},"acknowledge_privacy":{"version":"example","sha256":"example"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.vimine.network/v1/enroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "first_name": "example", "last_name": "example", "codicefiscale": "example", "codicefiscale_confirmed": true, "guardian": { "first_name": "example", "last_name": "example", "relation": "example", "codicefiscale": "example", "email": "hello@example.com", "phone": "example" }, "address": { "kind": "residence", "line": "example", "postal_code": "example", "city": "example", "province": "example", "country": "IT" }, "phone": "example", "dob": "2026-04-15", "gender": "M", "birthplace": "example", "birth_country": "example", "membership_type": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "locale": "example", "accept_statuto": { "version": 1, "sha256": "example" }, "privacy_notice": { "version": 1, "sha256": "example", "locale": "example" }, "accept_terms": { "version": "example", "sha256": "example" }, "acknowledge_privacy": { "version": "example", "sha256": "example" } }'

Creates the identity when the address is new and the membership request (issued ACTIVE at once for a free type with no approval gate, else PENDING until the association records the quota and/or approves). An address that already has a Vimine account is never linked silently: its owner receives a confirmation link and the request is created when they use it. Always answers 202. accept_statuto must name the in-force statuto version (and sha256 when published). Client tokens only (enroll:write); honours Idempotency-Key.

Authorizations

BearerToken
enroll:write
ClientBasic

Request Body^required

application/json

object

email

required

string format: email

first_name

required

string

<= 50 characters

last_name

required

string

<= 50 characters

codicefiscale

Optional. A person is identified by a fiscal code OR by dob + birthplace + birth_country — never neither (422 required on each missing particular). When present it is validated and cross-checked against the names, the date and the place (the state, for people born abroad)

string

nullable <= 16 characters

codicefiscale_confirmed

The person confirms a code that disagrees with their particulars (422 codicefiscale_mismatch with confirmable: true)

boolean

guardian

Who holds parental responsibility for a minor (under 18 by dob or, without it, by the birth date codicefiscale encodes). REQUIRED for a minor where the association declared it collects the block (aps.collects_guardian_data): 422 required on guardian otherwise; stored only where it declared so

object

first_name

required

string

<= 50 characters

last_name

required

string

<= 50 characters

relation

required

Parent, guardian… as the association records it

string

<= 20 characters

codicefiscale

Optional; refused when malformed

string

nullable <= 16 characters

email

string format: email

nullable

phone

string

nullable <= 20 characters

address

Residence or, where different, domicile. Asked of every member or of nobody: the public profile says what the association declared (member_address: none — ignored, not stored · optional · required — 422 required on address without it)

object

kind

string

default: residence

Allowed values: residence domicile

line

required

Street and number

string

<= 150 characters

postal_code

string

nullable <= 12 characters

city

required

string

<= 150 characters

province

Italian addresses only (two letters); dropped abroad

string

nullable <= 2 characters

country

ISO 3166-1 alpha-2

string

default: IT >= 2 characters <= 2 characters

phone

string

nullable <= 20 characters

dob

string format: date

nullable

gender

Demographic only: it is not cross-checked

string

nullable

Allowed values: M F

birthplace

Comune (born in Italy) or city, free text (born abroad)

string

nullable <= 150 characters

birth_country

ISO 3166-1 alpha-2

string

nullable >= 2 characters <= 2 characters

membership_type

One of the association’s membership types (omit when it has exactly one)

string format: uuid

locale

The language of the page the person filled in (a platform language — it, en, …; any other tag is matched to the platform’s own: en-GB → en, zh-TW → zh-Hant). It decides the language of the mails that follow and becomes the preference of a NEW account; an existing account keeps its own. Unsupported values are ignored

string

nullable

accept_statuto

required

The in-force statuto the person accepted on your site (from GET /v1/aps/{slug})

object

version

required

integer

sha256

string

privacy_notice

The association’s privacy notice the person read on your site (GET /v1/aps/{slug} → privacy_notice). REQUIRED when the association publishes one; 422 privacy_notice_outdated when it is not the in-force version

object

version

required

The in-force notice version shown (GET /v1/aps/{slug} → privacy_notice)

integer

sha256

string

locale

The language of the notice you showed (privacy_notice.locale of the answer you read it from). Each language is its own document, with its own version: name it when you read the profile with ?locale=. Default: the request’s locale, then the association’s language

string

accept_terms

The account terms (platform_terms) the person accepted on your site — optional, must name the in-force version

object

version

required

The in-force version label shown (GET /v1/legal/{kind})

string

sha256

Its template hash, when published

string

acknowledge_privacy

The platform privacy notice (platform_privacy) the person read — optional, same rule

object

version

required

The in-force version label shown (GET /v1/legal/{kind})

string

sha256

Its template hash, when published

string

Responses

202

Accepted

application/json

object

status

required

string

Allowed values: accepted

Example

{
  "status": "accepted"
}

400

Invalid request

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

code

required

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

401

Missing or invalid credentials

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

code

required

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

403

The association does not accept membership requests (api_disabled)

404

Not found

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

code

required

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

422

Validation failed, unknown membership type or accept_statuto does not name the in-force statuto

429

Rate limited

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

code

required

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

500

Internal error

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

string

code

required

string

request_id

string

errors

Array<object>

object

field

string

code

string

message

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

Submit a membership request for a person (server-side)

Authorizations

Request Bodyrequired

Responses

202

Example

400

Examplegenerated

401

Examplegenerated

403

404

Examplegenerated

422

429

Examplegenerated

500

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated