> For the complete documentation index, see [llms.txt](https://biz-card.gitbook.io/bizcard/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://biz-card.gitbook.io/bizcard/api-document/contacts.md).

# Contacts

Create, update, query, and delete contacts.

## Create contact

> Create a new contact.

```json
{"openapi":"3.0.3","info":{"title":"BizCard Contacts Open API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, query, and delete contacts."}],"servers":[{"url":"https://pre.card.biz","description":"Test (Pre)"},{"url":"https://card.biz","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key provided by BizCard. Send it in the `X-API-Key` header."}},"schemas":{"ContactSaveRequest":{"type":"object","required":["contactOwnerEmail","firstName","primaryEmail","updater","updateTime"],"properties":{"requestId":{"type":"string","description":"Request ID for tracing."},"contactOwnerEmail":{"type":"string","description":"Owner email of the contact."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"string"}},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalId":{"type":"string","description":"External system ID (unique under the same contactOwnerEmail)."},"externalRegistrationStatus":{"$ref":"#/components/schemas/ExternalRegistrationStatus"},"externalSubscriptionStatus":{"$ref":"#/components/schemas/ExternalSubscriptionStatus"},"updater":{"$ref":"#/components/schemas/Updater"},"updateTime":{"type":"string","format":"date-time"},"extParams":{"type":"object","additionalProperties":{"type":"string"}}}},"ExternalRegistrationStatus":{"type":"integer","enum":[0,1],"description":"External registration status: 0-unregistered, 1-registered."},"ExternalSubscriptionStatus":{"type":"integer","enum":[0,1,2,3],"description":"External subscription status: 0-none, 1-trial, 2-expired, 3-subscribed."},"Updater":{"type":"integer","enum":[1,2,3],"description":"Who performs the update: 1-UI manual, 2-Agent, 3-API."},"ApiResponseContact":{"type":"object","properties":{"code":{"type":"integer","description":"Business status code. 200 means success."},"message":{"type":"string","description":"Human readable message."},"data":{"$ref":"#/components/schemas/Contact"}},"required":["code","message","data"]},"Contact":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID."},"contactOwner":{"type":"string","description":"Owner email of the contact."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"string"}},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalId":{"type":"string","description":"External system ID (unique under the same contactOwnerEmail)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business error code."},"message":{"type":"string","description":"Error message."},"data":{"nullable":true}},"required":["code","message"]}},"responses":{"BadRequest":{"description":"Parameter error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"System error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/open/contact/save":{"post":{"summary":"Create contact","description":"Create a new contact.","operationId":"api_open_contact_save","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSaveRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseContact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Update contact

> Update an existing contact by contactId. Note: \`emails\` and \`phones\` are append mode.

```json
{"openapi":"3.0.3","info":{"title":"BizCard Contacts Open API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, query, and delete contacts."}],"servers":[{"url":"https://pre.card.biz","description":"Test (Pre)"},{"url":"https://card.biz","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key provided by BizCard. Send it in the `X-API-Key` header."}},"schemas":{"ContactUpdateRequest":{"type":"object","required":["contactId","updater","updateTime"],"properties":{"contactId":{"type":"string","description":"Contact ID."},"requestId":{"type":"string"},"contactOwnerEmail":{"type":"string","description":"Owner email can be updated."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"},"description":"Append mode (server will append)."},"phones":{"type":"array","items":{"type":"string"},"description":"Append mode (server will append)."},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalRegistrationStatus":{"$ref":"#/components/schemas/ExternalRegistrationStatus"},"externalSubscriptionStatus":{"$ref":"#/components/schemas/ExternalSubscriptionStatus"},"updater":{"$ref":"#/components/schemas/Updater"},"updateTime":{"type":"string","format":"date-time"},"extParams":{"type":"object","additionalProperties":{"type":"string"}}}},"ExternalRegistrationStatus":{"type":"integer","enum":[0,1],"description":"External registration status: 0-unregistered, 1-registered."},"ExternalSubscriptionStatus":{"type":"integer","enum":[0,1,2,3],"description":"External subscription status: 0-none, 1-trial, 2-expired, 3-subscribed."},"Updater":{"type":"integer","enum":[1,2,3],"description":"Who performs the update: 1-UI manual, 2-Agent, 3-API."},"ApiResponseContact":{"type":"object","properties":{"code":{"type":"integer","description":"Business status code. 200 means success."},"message":{"type":"string","description":"Human readable message."},"data":{"$ref":"#/components/schemas/Contact"}},"required":["code","message","data"]},"Contact":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID."},"contactOwner":{"type":"string","description":"Owner email of the contact."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"string"}},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalId":{"type":"string","description":"External system ID (unique under the same contactOwnerEmail)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business error code."},"message":{"type":"string","description":"Error message."},"data":{"nullable":true}},"required":["code","message"]}},"responses":{"BadRequest":{"description":"Parameter error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"System error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/open/contact/update":{"post":{"summary":"Update contact","description":"Update an existing contact by contactId. Note: `emails` and `phones` are append mode.","operationId":"api_open_contact_update","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpdateRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseContact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Query contact

> Query a contact by contactId.

```json
{"openapi":"3.0.3","info":{"title":"BizCard Contacts Open API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, query, and delete contacts."}],"servers":[{"url":"https://pre.card.biz","description":"Test (Pre)"},{"url":"https://card.biz","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key provided by BizCard. Send it in the `X-API-Key` header."}},"schemas":{"ApiResponseContact":{"type":"object","properties":{"code":{"type":"integer","description":"Business status code. 200 means success."},"message":{"type":"string","description":"Human readable message."},"data":{"$ref":"#/components/schemas/Contact"}},"required":["code","message","data"]},"Contact":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID."},"contactOwner":{"type":"string","description":"Owner email of the contact."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"string"}},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalId":{"type":"string","description":"External system ID (unique under the same contactOwnerEmail)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business error code."},"message":{"type":"string","description":"Error message."},"data":{"nullable":true}},"required":["code","message"]}},"responses":{"BadRequest":{"description":"Parameter error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"System error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/open/contact/query":{"get":{"summary":"Query contact","description":"Query a contact by contactId.","operationId":"getContactById","tags":["Contacts"],"parameters":[{"name":"contactId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseContact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Delete contact

> Delete a contact by contactId.

```json
{"openapi":"3.0.3","info":{"title":"BizCard Contacts Open API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, query, and delete contacts."}],"servers":[{"url":"https://pre.card.biz","description":"Test (Pre)"},{"url":"https://card.biz","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key provided by BizCard. Send it in the `X-API-Key` header."}},"schemas":{"ContactDeleteRequest":{"type":"object","required":["contactId","updater"],"properties":{"requestId":{"type":"string"},"contactId":{"type":"string"},"updater":{"$ref":"#/components/schemas/Updater"}}},"Updater":{"type":"integer","enum":[1,2,3],"description":"Who performs the update: 1-UI manual, 2-Agent, 3-API."},"ApiResponseEmpty":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"nullable":true}},"required":["code","message"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business error code."},"message":{"type":"string","description":"Error message."},"data":{"nullable":true}},"required":["code","message"]}},"responses":{"BadRequest":{"description":"Parameter error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"System error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/open/contact/delete":{"post":{"summary":"Delete contact","description":"Delete a contact by contactId.","operationId":"api_open_contact_delete","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactDeleteRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseEmpty"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Save or update contact

> If \`contactId\` is provided and exists, update; otherwise create. Prefer using \`/save\` or \`/update\` explicitly for clarity.

```json
{"openapi":"3.0.3","info":{"title":"BizCard Contacts Open API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Create, update, query, and delete contacts."}],"servers":[{"url":"https://pre.card.biz","description":"Test (Pre)"},{"url":"https://card.biz","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key provided by BizCard. Send it in the `X-API-Key` header."}},"schemas":{"ContactSaveOrUpdateRequest":{"type":"object","required":["contactId","updater","updateTime"],"properties":{"contactId":{"type":"string","description":"Contact ID."},"requestId":{"type":"string"},"contactOwnerEmail":{"type":"string","description":"Owner email can be updated."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"},"description":"Append mode (server will append)."},"phones":{"type":"array","items":{"type":"string"},"description":"Append mode (server will append)."},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalRegistrationStatus":{"$ref":"#/components/schemas/ExternalRegistrationStatus"},"externalSubscriptionStatus":{"$ref":"#/components/schemas/ExternalSubscriptionStatus"},"updater":{"$ref":"#/components/schemas/Updater"},"updateTime":{"type":"string","format":"date-time"},"extParams":{"type":"object","additionalProperties":{"type":"string"}}}},"ExternalRegistrationStatus":{"type":"integer","enum":[0,1],"description":"External registration status: 0-unregistered, 1-registered."},"ExternalSubscriptionStatus":{"type":"integer","enum":[0,1,2,3],"description":"External subscription status: 0-none, 1-trial, 2-expired, 3-subscribed."},"Updater":{"type":"integer","enum":[1,2,3],"description":"Who performs the update: 1-UI manual, 2-Agent, 3-API."},"ApiResponseContact":{"type":"object","properties":{"code":{"type":"integer","description":"Business status code. 200 means success."},"message":{"type":"string","description":"Human readable message."},"data":{"$ref":"#/components/schemas/Contact"}},"required":["code","message","data"]},"Contact":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID."},"contactOwner":{"type":"string","description":"Owner email of the contact."},"firstName":{"type":"string"},"lastName":{"type":"string"},"primaryEmail":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"string"}},"company":{"type":"string"},"department":{"type":"string"},"jobTitle":{"type":"string"},"country":{"type":"string"},"city":{"type":"string"},"externalId":{"type":"string","description":"External system ID (unique under the same contactOwnerEmail)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business error code."},"message":{"type":"string","description":"Error message."},"data":{"nullable":true}},"required":["code","message"]}},"responses":{"BadRequest":{"description":"Parameter error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Contact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"System error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/open/contact/saveOrUpdate":{"post":{"summary":"Save or update contact","description":"If `contactId` is provided and exists, update; otherwise create. Prefer using `/save` or `/update` explicitly for clarity.","operationId":"api_open_contact_saveOrUpdate","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSaveOrUpdateRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseContact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":true}}}}
```