Leads

Criar um lead

Cria um lead (prospect) num dos clubes do ginásio e devolve-o tal como ficou guardado. O lead nasce com o estado open e a fase new.

Requer o plano Pro ou Enterprise e o scope leads:write.

Campos obrigatórios: name, email, club_id e consents.data_processing (tem de ser true: só se cria um lead com consentimento para tratamento de dados). consents.marketing é opcional e, se faltar, fica false. Os campos de texto são aparados e uma string vazia num campo opcional conta como não enviado.

club_id tem de estar dentro dos clubes permitidos à API key (senão 403 club_forbidden). tax_country_id (ver GET /v1/countries), source_id (um motivo de inscrição, ver GET /v1/reasons?type=subscribe) e salesperson_id (um comercial ativo; ver GET /v1/staff no plano Enterprise ou pedir o id ao clube no plano Pro) têm de existir; se não existirem responde 400 invalid_reference.

Não há proteção contra duplicados: repetir o pedido cria outro lead. Emails e NIF que já existam no ginásio são aceites; é o clube que decide o que fazer com eles.

Os leads criados pela API ficam com a etiqueta #API na aplicação do ginásio, para os poderes filtrar.

Segurança:

  • Chama este endpoint só a partir do teu servidor, nunca de JavaScript no browser: a API key ficaria exposta a qualquer visitante do site.
  • Usa uma API key dedicada, só com o scope leads:write e restrita ao clube (ou clubes) de que precisas.
  • A proteção contra spam (captcha, limites por IP, etc.) no teu formulário é da tua responsabilidade: a API cria todos os leads válidos que receber.
post/v1/leads

Request

  • Base URL: https://api-public.mvf.pt
  • URL: https://api-public.mvf.pt/v1/leads
  • Auth: HTTP bearer

Request body

namestring required

Nome completo.

short_namestring

Nome curto.

emailstring email required
club_idstring required

Clube do lead (ver GET /v1/clubs); tem de ser permitido à API key.

mobile_phonestring
birthdaystring date
gender'male' | 'female' | 'other'
tax_numberstring

NIF.

tax_country_idstring

País do NIF (ver GET /v1/countries).

source_idstring

Fonte de angariação: um motivo de inscrição (ver GET /v1/reasons?type=subscribe).

salesperson_idstring

Comercial responsável, ativo (ver GET /v1/staff, que requer o plano Enterprise; no plano Pro pede ao clube o id do comercial).

Example request

{
  "name": "Ana Margarida Sousa",
  "short_name": "Ana Sousa",
  "email": "ana.sousa@example.pt",
  "club_id": "clb_1",
  "mobile_phone": "912345678",
  "birthday": "1992-05-14",
  "gender": "female",
  "tax_number": "123456789",
  "tax_country_id": "cty_-178",
  "address": {
    "line": "Rua Exemplo 12",
    "city": "Guimarães",
    "postal_code": "4800-001"
  },
  "source_id": "rsn_-3",
  "salesperson_id": "stf_3",
  "consents": {
    "data_processing": true
  }
}

Response

Lead criado.

idstring required

Identificador do lead.

club_idstring nullable required
namestring nullable required
short_namestring nullable required
emailstring nullable required
mobile_phonestring nullable required
birthdaystring date nullable required
gender'male' | 'female' | 'other' | 'null' nullable required

null se não estiver definido.

tax_numberstring nullable required
tax_country_idstring nullable required
source_idstring nullable required

Fonte de angariação.

salesperson_idstring nullable required
status'open' | 'won' | 'lost' | 'unknown' required

Estado do lead. Um lead novo está open.

stage'new' | 'follow_up' | 'scheduled' | 'sleeper' | 'other' required

Fase do lead. Um lead novo está em new.

created_atstring date-time nullable required

Criação (UTC).

Example response

{
  "id": "led_2001",
  "club_id": "clb_1",
  "name": "Ana Margarida Sousa",
  "short_name": "Ana Sousa",
  "email": "ana.sousa@example.pt",
  "mobile_phone": "912345678",
  "birthday": "1992-05-14",
  "gender": "female",
  "tax_number": "123456789",
  "tax_country_id": "cty_-178",
  "address": {
    "line": "Rua Exemplo 12",
    "city": "Guimarães",
    "postal_code": "4800-001"
  },
  "source_id": "rsn_-3",
  "salesperson_id": "stf_3",
  "consents": {
    "data_processing": true,
    "marketing": false
  },
  "status": "open",
  "stage": "new",
  "created_at": "2026-10-09T09:15:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.