Saltar al contenido principal

API Key External API (/api/ext)

Documentacion de endpoints externos protegidos con API Key.

Autenticacion​

Todos los endpoints de este documento usan:

Authorization: X-API-Key YOUR_API_KEY
Content-Type: application/json

Base URL:

https://api-staging.minotaursales.io/api/ext

Ejemplo:

curl --location '{API_GATEWAY_URL}/api/ext/contacts/list' \
  --header 'Authorization: X-API-Key YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

Formatos de respuesta comunes​

DefaultResponse​

Muchos endpoints de create/update/delete responden con:

{
  "success": true,
  "data": {},
  "message": "Operation completed"
}

PaginateResponse<T>​

{
  "data": [],
  "pagination": {
    "total_records": 0,
    "current_page": 1,
    "total_pages": 1
  }
}

Contacts (/contacts)​

POST /contacts/list (contacts:read)​

Request (ejemplo minimo):

{
  "filters": {},
  "paginate": {
    "page": 1,
    "limit": 25
  }
}

Response 200 (ContactsResponse[]):

[
  {
    "id": "7b9c3df7-0eb5-4be2-af74-7e48d4b43b9c",
    "first_name": "Ana",
    "middle_name": null,
    "last_name": "Perez",
    "gender": null,
    "birth_year": null,
    "linkedin_url": null,
    "facebook_url": null,
    "twitter_url": null,
    "work_email": "ana@example.com",
    "personal_email": null,
    "other_emails": null,
    "industry": "Software",
    "job_title": "Engineer",
    "location_locality": "Bogota",
    "location_country": "CO",
    "location_region": "Cundinamarca",
    "location_postal_code": null,
    "phone_numbers": [],
    "company": "Acme",
    "mobile_phone": null,
    "score": 87,
    "verification_status": "verified",
    "last_verified": "2026-04-01T10:30:00.000Z",
    "custom_fields": {}
  }
]

POST /contacts/metadata (contacts:read)​

Request:

{
  "filters": {},
  "paginate": {
    "page": 1,
    "limit": 25
  }
}

Response 200 (ContactMetadataResponse):

{
  "pagination": {
    "current_page": 1,
    "total_records": 1,
    "total_pages": 1
  }
}

POST /contacts (contacts:create)​

Campos requeridos para create:

  • first_name
  • last_name
  • work_email
  • phone_numbers (puede ser arreglo vacio)

Request:

{
  "first_name": "Ana",
  "last_name": "Perez",
  "work_email": "ana@example.com",
  "phone_numbers": [],
  "job_title": "Engineer",
  "company": "Acme"
}

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {
    "id": "7b9c3df7-0eb5-4be2-af74-7e48d4b43b9c"
  },
  "message": "Contact created"
}

GET /contacts/:id (contacts:read)​

Response 200 (ContactsResponse):

{
  "id": "7b9c3df7-0eb5-4be2-af74-7e48d4b43b9c",
  "first_name": "Ana",
  "middle_name": null,
  "last_name": "Perez",
  "gender": null,
  "birth_year": null,
  "linkedin_url": null,
  "facebook_url": null,
  "twitter_url": null,
  "work_email": "ana@example.com",
  "personal_email": null,
  "other_emails": null,
  "industry": "Software",
  "job_title": "Engineer",
  "location_locality": "Bogota",
  "location_country": "CO",
  "location_region": "Cundinamarca",
  "location_postal_code": null,
  "phone_numbers": [],
  "company": "Acme",
  "mobile_phone": null,
  "score": 87,
  "verification_status": "verified",
  "last_verified": "2026-04-01T10:30:00.000Z",
  "custom_fields": {}
}

PATCH /contacts/:id (contacts:update)​

Request:

{
  "job_title": "Senior Engineer",
  "phone_numbers": ["+573001234567"]
}

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "Contact updated"
}

DELETE /contacts/:id (contacts:delete)​

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "Contact deleted"
}

Companies (/company)​

POST /company/list (companies:read)​

Request:

{
  "filters": {},
  "paginate": {
    "page": 1,
    "limit": 25
  }
}

Response 200 (CompaniesResponse[]):

[
  {
    "id": "30ea8d4e-6b76-4f8f-bcf8-a1cc5af13b4b",
    "company_name": "Acme Inc",
    "size": "51-200",
    "industry": "Software",
    "twitter_url": null,
    "linkedin_url": "https://linkedin.com/company/acme",
    "facebook_url": null,
    "location_locality": "Bogota",
    "location_metro": null,
    "location_region": "Cundinamarca",
    "location_street_address": null,
    "location_address_line_2": null,
    "location_postal_code": null,
    "location_country": "CO",
    "last_verified": "2026-04-01T10:30:00.000Z",
    "verification_status": "verified",
    "score": 80,
    "custom_fields": {}
  }
]

POST /company/metadata (companies:read)​

Request:

{
  "filters": {},
  "paginate": {
    "page": 1,
    "limit": 25
  }
}

Response 200 (CompanyMetadataResponse):

{
  "pagination": {
    "current_page": 1,
    "total_records": 1,
    "total_pages": 1
  }
}

POST /company (companies:create)​

Campos requeridos para create:

  • type
  • company_name

Request:

{
  "type": "company",
  "company_name": "Acme Inc",
  "industry": "Software"
}

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {
    "id": "30ea8d4e-6b76-4f8f-bcf8-a1cc5af13b4b"
  },
  "message": "Company created"
}

GET /company/:id (companies:read)​

Response 200 (CompaniesResponse | null):

{
  "id": "30ea8d4e-6b76-4f8f-bcf8-a1cc5af13b4b",
  "company_name": "Acme Inc",
  "size": "51-200",
  "industry": "Software",
  "twitter_url": null,
  "linkedin_url": "https://linkedin.com/company/acme",
  "facebook_url": null,
  "location_locality": "Bogota",
  "location_metro": null,
  "location_region": "Cundinamarca",
  "location_street_address": null,
  "location_address_line_2": null,
  "location_postal_code": null,
  "location_country": "CO",
  "last_verified": "2026-04-01T10:30:00.000Z",
  "verification_status": "verified",
  "score": 80,
  "custom_fields": {}
}

PATCH /company/:id (companies:update)​

Request:

{
  "industry": "SaaS",
  "location_country": "CO"
}

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "Company updated"
}

DELETE /company/:id (companies:delete)​

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "Company deleted"
}

Lists (/list-contact)​

POST /list-contact (list_contacts:create)​

Request:

{
  "name": "Prospects Latam",
  "description": "Lista inicial",
  "rules": [
    {
      "field": "location_country",
      "operator": "contains",
      "value": "CO"
    }
  ]
}

Response 200 (CreateListContactResponse):

{
  "id": "9f720ce2-f5d1-4ef4-a0c8-3399f68d386d",
  "name": "Prospects Latam"
}

POST /list-contact/list (list_contacts:read)​

Request:

{
  "paginate": {
    "page": 1,
    "limit": 25
  },
  "filters": {}
}

Response 200 (PaginateResponse<ListContactResponse>):

{
  "data": [
    {
      "id": "9f720ce2-f5d1-4ef4-a0c8-3399f68d386d",
      "name": "Prospects Latam",
      "description": "Lista inicial",
      "owner_id": "6cbe57bf-bf80-44c0-a2f7-8d6d4ca85dbd",
      "owner_name": "API Owner",
      "source": "manual",
      "collaborators": [],
      "rules": [
        {
          "field": "location_country",
          "operator": "contains",
          "value": "CO",
          "logic_operator": "AND"
        }
      ],
      "contacts_count": 120,
      "created_at": "2026-04-01T10:30:00.000Z",
      "updated_at": "2026-04-01T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total_records": 1,
    "current_page": 1,
    "total_pages": 1
  }
}

PATCH /list-contact/:id (list_contacts:update)​

Request:

{
  "name": "Prospects Latam v2",
  "description": "Lista actualizada"
}

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "List updated"
}

DELETE /list-contact/:id (list_contacts:delete)​

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "List deleted"
}

POST /list-contact/duplicate (list_contacts:read)​

Request:

{
  "list_id": "9f720ce2-f5d1-4ef4-a0c8-3399f68d386d",
  "new_name": "Prospects Latam Copy"
}

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "List duplicated"
}

POST /list-contact/verify-contacts/:id (list_contacts:read)​

Request: sin body.

Response 200 (DefaultResponse):

{
  "success": true,
  "data": {},
  "message": "Verification started"
}

Prospect (/prospect)​

POST /prospect/filters (prospect:read)​

Request (FiltersDto):

{
  "source": "job_title",
  "search": "engineer"
}

Response 200 (lista de valores sugeridos):

[
  {
    "type": "job_title",
    "value": "Software Engineer"
  }
]

POST /prospect/metadata (prospect:read)​

Request (GetBatchContactsDto):

{
  "filters": {},
  "paginate": {
    "page": 1,
    "limit": 25
  },
  "all_contacts": false
}

Response 200 (MetadataContactFilterResponse):

{
  "pagination": {
    "current_page": 1,
    "total_records": 1200,
    "total_pages": 48
  },
  "filters_applied": {
    "first_name": [],
    "last_name": [],
    "job_title": [],
    "job_company_name": [],
    "job_company_industry": [],
    "location_locality": [],
    "location_region": [],
    "location_country": [],
    "location_postal_code": [],
    "date_verified": {
      "gte": null,
      "lte": null
    }
  }
}

POST /prospect/list (prospect:read)​

Request (GetBatchContactsDto):

{
  "filters": {},
  "paginate": {
    "page": 1,
    "limit": 25
  },
  "all_contacts": false
}

Response 200 (ProspectContactResponse[]):

[
  {
    "_id": "6638f0f0507f4b2cb54f4f3e",
    "first_name": "Ana",
    "last_name": "Perez",
    "job_title": "Engineer",
    "job_company_name": "Acme",
    "job_company_industry": "Software",
    "work_email": "ana@example.com",
    "emails": ["ana@example.com"],
    "mobile_phone": null,
    "location_locality": "Bogota",
    "location_region": "Cundinamarca",
    "location_country": "CO",
    "location_postal_code": null,
    "facebook_url": null,
    "linkedin_url": null,
    "twitter_url": null,
    "verification_status": "verified",
    "score": 82,
    "date_verified": "2026-04-01T10:30:00.000Z"
  }
]

Service Handler (/service-handler)​

POST /service-handler/unlock-contacts (payment_prospect:create)​

Request (UnlockContactsDto):

{
  "filters": {},
  "order_by": {
    "score": "DESC"
  },
  "total_records": 100,
  "sync_hubspot": false
}

Response 200 (ServiceHandlerResponse):

{
  "id": "7ec0d9c6-cab6-46cf-8d5a-b5f22f17f6da",
  "status": "PENDING"
}

POST /service-handler/unlock-selected-contacts (payment_prospect:create)​

Request (UnlockSelectedContactsDto):

{
  "ids": [
    "7b9c3df7-0eb5-4be2-af74-7e48d4b43b9c",
    "a96f2d7f-743f-4747-9198-7ca35ccab774"
  ],
  "sync_hubspot": false
}

Response 200 (ServiceHandlerResponse):

{
  "id": "dc7248f7-bc52-4710-b854-a8caac8ca5a6",
  "status": "PENDING"
}

POST /service-handler/verify-email (verify_email:create)​

Request (VerifyEmailDto):

{
  "emails": [
    {
      "email": "ana@example.com",
      "contact_id": "7b9c3df7-0eb5-4be2-af74-7e48d4b43b9c"
    }
  ],
  "sync_hubspot": false
}

Response 200 (ServiceHandlerResponse):

{
  "id": "f2c4f038-63fc-4f78-a86d-88f26a7398d8",
  "status": "PENDING"
}

Errores frecuentes​

401 Unauthorized​

Cuando falta o es invalido el header Authorization:

{
  "statusCode": 401,
  "message": "The provided API key is invalid or unauthorized."
}

400 Bad Request​

Cuando el body no cumple validaciones (campos requeridos, UUID invalido, tipos incorrectos).