Create Bulk Contacts vCards

POST

/v1/contacts/import/vcards

Parses one or more vCard strings (the standard .vcf contact format used by phones/email clients) and bulk-creates/updates contacts from them.

vCard field mapping:

vCard line	Maps to
`FN:`	`name`
`TEL...:`	`phoneNumber` (parses past `TEL;type=CELL;...:` prefixes to the actual number)
`EMAIL...:`	`email`
`ORG:`	`company`
`TITLE:`	`position`

Duplicate handling : when a parsed contact's phone number already exists, duplicateStrategy controls what happens:

Value	Name	Behavior
1	Skip (default)	Leave the existing contact untouched
2	Update	Overwrite the existing contact with the imported data
3	Error	Mark that entry as failed instead of touching the existing contact

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Per-vCard import results.

Bodyapplication/json

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.voxa.sa/v1/contacts/import/vcards' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "vCards": [
        "BEGIN:VCARD\nVERSION:3.0\nFN:Ahmed Al-Otaibi\nTEL:+966501234567\nEMAIL:ahmed@example.com\nORG:Acme Co\nTITLE:Manager\nEND:VCARD"
    ],
    "duplicateStrategy": 1
}'

Response Example

{
    "totalContacts": 1,
    "successCount": 1,
    "failedCount": 0,
    "skippedCount": 0,
    "updatedCount": 0,
    "results": [
        {
            "phoneNumber": "+966501334567",
            "name": "Ahmed Noshy",
            "contactId": "3a21f3...............",
            "isSuccess": true,
            "status": 1,
            "errorMessage": null
        }
    ]
}

Modified at 2026-06-19 18:59:38

Get Contact By Id

Contacts History