{ "openapi": "3.1.0", "info": { "title": "iFlora Care API", "version": "1.0.0", "description": "Find home care companies and senior residences in Brazil on behalf of a family. Same functions as the MCP server at https://www.iflora.com.br/care/mcp. Plataforma operada pela iFlora (iflora.com.br). As informações do pedido são usadas apenas para encontrar prestadores compatíveis e encaminhar o caso, sem nomes, aos prestadores escolhidos pela família. O contato da família só é enviado aos prestadores que aceitarem o caso. Os dados são apagados ou anonimizados após 24 meses sem atividade, ou antes, a pedido da família. A iFlora Care verifica informações declaradas pelos prestadores, não a qualidade do cuidado nem a disponibilidade de vagas.", "contact": { "url": "https://www.iflora.com.br/care/para-assistentes" } }, "servers": [ { "url": "https://www.iflora.com.br/care/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/agents": { "post": { "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_name": { "type": "string", "description": "Name of your assistant or app, e.g. \"ChatGPT\" or \"Claude\"." }, "operator": { "type": "string", "description": "Company or person operating the assistant (optional)." }, "contact_email": { "type": "string", "description": "Technical contact email (optional)." } }, "required": [ "agent_name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "API key created (data.api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "operationId": "register_agent", "summary": "Get an iFlora Care API key", "description": "Returns a free iFlora Care API key instantly. Call this once, keep the key, and reuse it for every later call. No family information is needed. iFlora Care (iflora.com.br) helps families in Brazil find home care companies and senior residences (ILPIs, casas de repouso, residenciais sêniores) anywhere in the country." } }, "/requests": { "post": { "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "qualification": { "type": "object", "description": "Answers about the person who needs care: who, age and location now; anything else only if already known. No names or contact details.", "properties": { "who_needs_care": { "type": "object", "description": "Relationship of the person to whoever is asking.", "properties": { "value": { "type": "string", "enum": [ "spouse", "parent", "self", "other" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "age": { "type": "object", "description": "Age of the person who needs care.", "properties": { "value": { "type": "integer", "minimum": 18, "maximum": 120 }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "location": { "type": "object", "description": "Where care is needed (home care) or around where the family wants a residence.", "properties": { "value": { "type": "object", "properties": { "state": { "type": "string", "description": "UF, e.g. \"SP\"." }, "municipality": { "type": "string", "description": "Municipality name (e.g. \"Campinas\") or 7-digit IBGE code." }, "bairro": { "type": "string", "description": "Neighborhood (optional)." }, "cep": { "type": "string", "description": "CEP, 8 digits (optional)." }, "max_distance_km": { "type": "string", "enum": [ "under_15", "15_30", "30_50", "over_50", "same_municipality" ], "description": "For senior residences: how far from this municipality the family accepts (optional; default 15_30)." } }, "required": [ "state", "municipality" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "care_setting": { "type": "object", "description": "Home care at the person's home, a senior residence, or both (default both).", "properties": { "value": { "type": "string", "enum": [ "home_care", "senior_living", "both" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "preferred_service_models": { "type": "object", "description": "Optional: residence types the family prefers.", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "ilpi", "residencial_senior", "residencia_assistida", "centro_dia" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "living_situation": { "type": "object", "description": "Where the person is now.", "properties": { "value": { "type": "string", "enum": [ "home_alone", "home_with_someone", "senior_living", "hospital", "rehab_or_nursing_facility" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "mobility": { "type": "object", "description": "Mobility.", "properties": { "value": { "type": "string", "enum": [ "independent", "cane", "walker", "wheelchair", "immobile", "bedridden" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "help_needed": { "type": "object", "description": "Daily help needed (empty list if none).", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "medication", "bathing", "toileting", "diabetic_care", "special_diet", "housekeeping", "social_activities" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "memory_loss": { "type": "object", "description": "Any memory loss or dementia diagnosis.", "properties": { "value": { "type": "string", "enum": [ "yes", "no" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "behaviors": { "type": "object", "description": "Behaviors (empty list if none).", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "wandering", "exit_seeking", "aggressiveness", "hallucinations", "withdrawal", "sundowning", "loss_of_judgment", "needs_24h_supervision" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "start_date": { "type": "object", "description": "When care should start.", "properties": { "value": { "type": "string", "enum": [ "today", "after_hospital_discharge", "this_week", "researching" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] }, "date": { "type": "string", "description": "Expected hospital discharge date, YYYY-MM-DD (required for after_hospital_discharge)." } }, "required": [ "value", "source" ] }, "schedule": { "type": "object", "description": "Home care schedule, e.g. \"12x36_day\", \"12x36_night\", \"24h\" or specific hours.", "properties": { "value": { "type": "string" }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "expected_duration": { "type": "object", "description": "E.g. \"temporary\", \"ongoing\" or free text.", "properties": { "value": { "type": "string" }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "professional_type": { "type": "object", "description": "Type of professional needed.", "properties": { "value": { "type": "string", "enum": [ "caregiver", "nursing_technician", "nurse", "combination" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "clinical_details": { "type": "object", "description": "Clinical needs (empty list if none).", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "recent_hospitalization", "wounds", "catheter", "feeding_tube", "oxygen", "ostomy", "other" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] }, "has_prescription": { "type": "string", "enum": [ "yes", "no" ], "description": "Whether there is a medical prescription for the care." } }, "required": [ "value", "source" ] }, "payment": { "type": "object", "description": "How care will be paid.", "properties": { "value": { "type": "string", "enum": [ "private", "health_plan" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] } }, "required": [ "who_needs_care", "age", "location" ] }, "processing_consent": { "type": "boolean", "description": "true if the family agreed to the processing consent text (required only when health details are included)." }, "processing_consent_text_version": { "type": "string", "description": "Version of the processing consent text shown: \"processing-v1-2026-10\"." } }, "required": [ "qualification" ] } } } }, "responses": { "201": { "description": "Request saved; data.matches lists matching providers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "operationId": "start_request", "summary": "Describe the care need and get matching providers", "description": "Step 1 of 2. Find home care companies and/or senior residences for an older person in Brazil. Only THREE answers are needed now: who needs care (relationship), their age, and where (state + municipality). Do not ask anything else before calling; if the family already mentioned other details (care setting, distance, mobility, memory loss...), include them, otherwise leave them out. iFlora Care saves the request and returns matching providers, ranked. Do NOT include names, phone numbers or emails.\n\nEach answer is {\"value\": ..., \"source\": \"family_confirmed\" | \"agent_filled\"} (family_confirmed if the family said it). Health details (mobility, memory, clinical needs, etc.) are sensitive data under Brazilian law (LGPD): only include them if the family agreed to this text, shown in Portuguese: \"Autorizo a iFlora Care a usar as informações de saúde e de cuidado que compartilhei para encontrar prestadores de cuidado compatíveis. Meu nome e meus contatos não são pedidos nesta etapa.\" — then also send processing_consent=true and processing_consent_text_version=\"processing-v1-2026-10\". Talk to the family in Portuguese.\n\nResults: \"assumptions\" says what was assumed (e.g. residences within 30 km). Requirements labelled \"não confirmado\" mean the provider has not yet confirmed it offers what the family needs. stale=true means not re-checked in 6 months. iFlora Care verifies facts stated by providers (licenses, registrations, services offered); it does not assess care quality or guarantee availability. If nothing matches, say so plainly and offer the suggestions returned; the request stays saved. next_step lists the remaining questions to ask only when the family is ready to send the case." } }, "/requests/{ref}": { "get": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "public_ref returned by start_request" } ], "responses": { "200": { "description": "Case cards and next options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "operationId": "get_request_status", "summary": "Follow the providers' answers", "description": "Status of each case card of a request: pending, contacting, accepted, declined (with reason) or expired (no answer within 2 business days, counted as declined). When every provider declined or expired, next_options lists other matching providers the family can choose (send them with send_request). Only the agent that created the request can read it." } }, "/requests/{ref}/providers/{id}": { "get": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "public_ref returned by start_request" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "provider_id from the matches" } ], "responses": { "200": { "description": "Full provider record with fact statuses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "operationId": "get_provider", "summary": "Read one matched provider in full", "description": "Full record of one provider returned by start_request (or by get_request_status next_options) for this public_ref: every fact with its status (verified, unverified, self-declared, unknown), source type and date. Only providers that matched this request can be read. iFlora Care verifies facts stated by providers (licenses, registrations, services offered); it does not assess care quality or guarantee availability." } }, "/requests/{ref}/send": { "post": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "public_ref returned by start_request" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chosen_provider_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3, "description": "provider_id values the family chose (1 to 3)." }, "qualification": { "type": "object", "description": "Remaining answers (same format as start_request); required ones: living_situation, mobility, memory_loss, start_date, payment.", "properties": { "who_needs_care": { "type": "object", "description": "Relationship of the person to whoever is asking.", "properties": { "value": { "type": "string", "enum": [ "spouse", "parent", "self", "other" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "age": { "type": "object", "description": "Age of the person who needs care.", "properties": { "value": { "type": "integer", "minimum": 18, "maximum": 120 }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "location": { "type": "object", "description": "Where care is needed (home care) or around where the family wants a residence.", "properties": { "value": { "type": "object", "properties": { "state": { "type": "string", "description": "UF, e.g. \"SP\"." }, "municipality": { "type": "string", "description": "Municipality name (e.g. \"Campinas\") or 7-digit IBGE code." }, "bairro": { "type": "string", "description": "Neighborhood (optional)." }, "cep": { "type": "string", "description": "CEP, 8 digits (optional)." }, "max_distance_km": { "type": "string", "enum": [ "under_15", "15_30", "30_50", "over_50", "same_municipality" ], "description": "For senior residences: how far from this municipality the family accepts (optional; default 15_30)." } }, "required": [ "state", "municipality" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "care_setting": { "type": "object", "description": "Home care at the person's home, a senior residence, or both (default both).", "properties": { "value": { "type": "string", "enum": [ "home_care", "senior_living", "both" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "preferred_service_models": { "type": "object", "description": "Optional: residence types the family prefers.", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "ilpi", "residencial_senior", "residencia_assistida", "centro_dia" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "living_situation": { "type": "object", "description": "Where the person is now.", "properties": { "value": { "type": "string", "enum": [ "home_alone", "home_with_someone", "senior_living", "hospital", "rehab_or_nursing_facility" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "mobility": { "type": "object", "description": "Mobility.", "properties": { "value": { "type": "string", "enum": [ "independent", "cane", "walker", "wheelchair", "immobile", "bedridden" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "help_needed": { "type": "object", "description": "Daily help needed (empty list if none).", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "medication", "bathing", "toileting", "diabetic_care", "special_diet", "housekeeping", "social_activities" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "memory_loss": { "type": "object", "description": "Any memory loss or dementia diagnosis.", "properties": { "value": { "type": "string", "enum": [ "yes", "no" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "behaviors": { "type": "object", "description": "Behaviors (empty list if none).", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "wandering", "exit_seeking", "aggressiveness", "hallucinations", "withdrawal", "sundowning", "loss_of_judgment", "needs_24h_supervision" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "start_date": { "type": "object", "description": "When care should start.", "properties": { "value": { "type": "string", "enum": [ "today", "after_hospital_discharge", "this_week", "researching" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] }, "date": { "type": "string", "description": "Expected hospital discharge date, YYYY-MM-DD (required for after_hospital_discharge)." } }, "required": [ "value", "source" ] }, "schedule": { "type": "object", "description": "Home care schedule, e.g. \"12x36_day\", \"12x36_night\", \"24h\" or specific hours.", "properties": { "value": { "type": "string" }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "expected_duration": { "type": "object", "description": "E.g. \"temporary\", \"ongoing\" or free text.", "properties": { "value": { "type": "string" }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "professional_type": { "type": "object", "description": "Type of professional needed.", "properties": { "value": { "type": "string", "enum": [ "caregiver", "nursing_technician", "nurse", "combination" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] }, "clinical_details": { "type": "object", "description": "Clinical needs (empty list if none).", "properties": { "value": { "type": "array", "items": { "type": "string", "enum": [ "recent_hospitalization", "wounds", "catheter", "feeding_tube", "oxygen", "ostomy", "other" ] } }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] }, "has_prescription": { "type": "string", "enum": [ "yes", "no" ], "description": "Whether there is a medical prescription for the care." } }, "required": [ "value", "source" ] }, "payment": { "type": "object", "description": "How care will be paid.", "properties": { "value": { "type": "string", "enum": [ "private", "health_plan" ] }, "source": { "type": "string", "enum": [ "family_confirmed", "agent_filled" ] } }, "required": [ "value", "source" ] } } }, "processing_consent": { "type": "boolean", "description": "true if the family agreed to the processing consent text (needed if not given at start_request)." }, "processing_consent_text_version": { "type": "string", "description": "Version of the processing consent text shown: \"processing-v1-2026-10\"." }, "sharing_consent": { "type": "boolean", "description": "true only if the family agreed to the sharing consent text." }, "sharing_consent_text_version": { "type": "string", "description": "Version of the sharing consent text shown: \"sharing-v1-2026-10\"." }, "family_contact": { "type": "object", "description": "Contact of the family member the providers should talk to.", "properties": { "name": { "type": "string" }, "phone_whatsapp": { "type": "string", "description": "Brazilian phone with area code (DDD), preferably WhatsApp." }, "email": { "type": "string" } }, "required": [ "name", "phone_whatsapp", "email" ] } }, "required": [ "chosen_provider_ids", "sharing_consent", "sharing_consent_text_version", "family_contact" ] } } } }, "responses": { "201": { "description": "Case cards created with deadlines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "operationId": "send_request", "summary": "Send the anonymized case to up to 3 providers", "description": "Step 2 of 2, after the family has seen the matches and chosen 1 to 3 providers. iFlora Care sends each chosen provider an anonymized case card and contacts it; providers answer within 2 business days. The family's name, phone/WhatsApp and email are shared ONLY with providers that accept the case.\n\nNOW ask the remaining questions (listed in start_request next_step.questions_still_needed): where the person is now, mobility, memory loss, when care should start and how it will be paid; optionally daily help needed, behaviors, clinical needs, schedule and professional type. Put the answers in qualification (same format as start_request).\n\nPRIVACY: show the family, in Portuguese, the consent texts and send only if they agree: (1) unless already given at start_request, processing: \"Autorizo a iFlora Care a usar as informações de saúde e de cuidado que compartilhei para encontrar prestadores de cuidado compatíveis. Meu nome e meus contatos não são pedidos nesta etapa.\" -> processing_consent=true, processing_consent_text_version=\"processing-v1-2026-10\"; (2) sharing: \"Autorizo a iFlora Care a enviar meu caso, sem meu nome, aos prestadores que escolhi, e a passar meu nome, telefone/WhatsApp e e-mail somente aos que aceitarem o caso.\" -> sharing_consent=true, sharing_consent_text_version=\"sharing-v1-2026-10\". Ask for their contact details; never invent them. If warnings come back, tell the family. Use get_request_status later." } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from POST /agents" } }, "schemas": { "Notice": { "type": "object", "properties": { "operator": { "type": "string" }, "data_use": { "type": "string" }, "verification": { "type": "string" } } }, "Success": { "type": "object", "properties": { "data": { "type": "object" }, "notice": { "$ref": "#/components/schemas/Notice" } }, "required": [ "data", "notice" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "notice": { "$ref": "#/components/schemas/Notice" } } } }, "responses": { "Error": { "description": "Error with a machine-readable code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }