1. Contacts
VeloConnect API
  • Velo services APIs
    • Getting Started
      • Introduction
      • Quick start: send your first SMS
      • Authentication
      • Errors
      • Limits
      • Delivery reports
      • Addresses and formats
      • Code samples
      • Viber and WhatsApp push reports
      • Refusal reasons
      • Changelog
      • Recipes
        • One-time code by SMS
        • One-time code by Viber, with SMS as a fallback
        • A campaign, from contacts to result
        • Connect a CRM
    • Messaging API (API Key)
      • Send SMS
        • Send SMS
        • Send SMS (GET form)
        • Send SMS to many numbers
        • Send SMS to many numbers (GET form)
      • SMS Delivery Status
        • List SMS records
        • Get an SMS record
      • SMS Verification Codes
        • Send a verification code (GET form)
        • Send a verification code
        • Check a verification code (GET form)
        • Check a verification code
      • Sender Names
        • List sender names (GET form)
        • List sender names
        • Get sender name status (GET form)
        • Get sender name status
      • Balance & Prices
        • Check balance (GET form)
        • Check balance
        • List rate plans
      • Viber
        • Campaigns
          • Send a Viber campaign
          • List Viber campaigns
        • Contact Lists
          • Create a Viber contact list
          • List Viber contact lists
          • Delete a Viber contact list
          • Add contacts to a list
          • Update contacts in a list
          • Delete a contact from a list
          • List contacts in a list
        • Conversations
          • List Viber conversations
          • List messages of a conversation
        • Message Records
          • List Viber message records
          • Get a Viber message record
        • Totals
          • Get Viber message totals
        • One-Time Codes
          • Send a Viber one-time code
          • List Viber code templates
        • Senders
          • Get a Viber sender
          • List Viber senders
        • Templates
          • Create a Viber template
          • List Viber templates
          • Delete a Viber template
          • Get a Viber template
      • WhatsApp
        • Senders
          • List WhatsApp senders
        • Campaigns
          • Send a WhatsApp campaign
          • List WhatsApp campaigns
        • Contact Lists
          • Add WhatsApp contacts
          • List WhatsApp contacts
          • Delete a WhatsApp contact list
          • Create a WhatsApp contact list
          • List WhatsApp contact lists
        • Contacts
          • Update WhatsApp contacts
          • Delete a WhatsApp contact
        • Conversations
          • List conversation messages
          • List WhatsApp conversations
        • Messages
        • Templates
          • Delete a WhatsApp template
          • Create a WhatsApp template
          • List WhatsApp templates
      • Cascading (Channel Fallback)
        • Cascading: send with channel fallback
    • Sign-In & Account
      • Team Members
      • Registration
      • Reference Data
      • Verification & Password
      • Two-Factor
      • Authentication
        • Sign in (for programs)
        • Refresh the login token
        • Sign out
      • Profile
        • Get your account profile
    • API Key & Allowed IPs
      • Get the API key
      • Replace the API key
      • Get the allowed IP addresses
      • Set the allowed IP addresses
    • Campaigns (v2)
      • Campaigns
        • Create a campaign
        • Export campaigns to CSV
        • List campaigns
        • Get a campaign
        • Update a campaign
      • Tools & Pricing
        • Count SMS parts
        • Calculate campaign price
        • Preview campaign recipients
      • Messages
      • Telegram
    • Contacts (v2)
      • Contacts
        • Create a contact
          POST
        • Export contacts
          POST
        • Import contacts from CSV
          POST
        • List contacts
          POST
        • Get a contact
          GET
        • Update a contact
          PUT
        • Delete a contact
          DELETE
      • Details
        • Add a contact detail
        • Export contact details
        • List contact details
        • Update a contact detail
      • Messages
        • Export a contact's messages
        • List a contact's messages
    • Segments (v2)
      • Create a segment
      • Export segments to CSV
      • List segments
      • Get a segment
      • Update a segment
      • Delete a segment
      • Add contacts to a segment
      • Remove contacts from a segment
    • Dashboard (v2)
      • Get channel breakdown
      • Get headline statistics
      • Get OTP statistics
      • Get message trends
    • Templates & Content
      • Canned Responses
      • Templates
        • Create a message template
        • List message templates
        • Update a message template
        • Delete a message template
        • Get a message template
      • Uploads
    • Sender Names & Rates
      • Rates
        • List message rates
      • Sender Names
        • Request a sender name
        • List sender names
        • Delete a sender name
        • Get a sender name
      • Reference Data
        • List trunks
        • List mobile operators
    • SMS Messaging
      • Conversations
        • List SMS conversations
        • List conversation messages
      • Delivery Records
        • Export SMS records
    • Email Messaging
      • Delivery Records
        • Export e-mail records
        • List e-mail records
        • Get an e-mail record
      • Pricing
        • List e-mail prices
    • Notifications & Statistics
      • Notifications
      • Statistics
        • List balance history
        • Get sender name expenses
    • Payments
      • Payments
        • List payments
        • Get a payment
      • Provider Callbacks
    • Link Shortener
      • Links
        • Create a short link
        • Get a link by code
        • Get a link
        • Update a link
        • Delete a link
      • Webhooks
      • Redirect
        • Open a short link
      • Analytics
        • Get statistics for several campaigns
        • Get campaign statistics
        • Get contact statistics
        • Get link statistics
    • Social Platform
      • Connections
        • List social connections
        • Get a channel
        • Disconnect a channel
        • Check channel subscription status
        • Get a connection
        • Disconnect a connection
        • Check a connection token
        • Resync channels of a connection
        • List supported providers
      • Inbox
        • List conversations of an account
        • List conversations of a channel
        • Sync conversations of a channel
        • Get a conversation
        • Get conversation status history
        • Mark a conversation as read
        • List messages of a conversation
        • Reply to a conversation
        • Sync messages of a conversation
      • Facebook
      • Instagram
      • Telegram
    • Telephony
      • DID Numbers
        • Purchase & Provisioning
        • Assignments
        • Catalog
        • Compliance
        • Orders
        • Reservations
      • PBX Tenants
      • SIP Voice
        • Monitoring
        • Calls
        • Session
    • Schemas
      • TemplateFilteringSortingModel
      • SocialChannelType
      • V2ContactDetailType
      • CommunicationType
      • RateFilteringSortingModel
      • PagedListGetModelOfV2ContactGetModel
      • SuccessResponseModelOfPagedListGetModelOfRateGetModel
      • SenderIdFilteringSortingModel
      • V2CampaignChannelGetModel
      • V2CampaignExportRequestModel
      • WebhookSubscriptionStatusDto
      • SocialProvider
      • V2CampaignChannelUpdateModel
      • SuccessResponseModelOfSenderIdGetModel
      • V2SegmentUpdateModel
      • V2ContactCsvDuplicateModel
      • PagedListGetModelOfRateGetModel
      • V2ContactMessageExportRequestModel
      • V2DashboardTrendsChannelModel
      • DataRecordFilterModel
      • SyncConversationsResponseDto
      • ClickEventDto
      • PagedListGetModelOfV2CampaignListItemModel
      • SocialConnectionDto
      • ErrorResponseModel
      • V2ContactCreateModel
      • V2SegmentContactsUpdateModel
      • TokenStatus
      • SuccessResponseModelOfV2ContactCsvImportResultModel
      • SuccessResponseModelOfEmailPriceGetModel
      • CustomerUserGetModel
      • V2ContactCsvImportResultModel
      • V2ContactDetailCreateModel
      • V2CampaignUpdateModel
      • SocialConversationDto
      • UnifiedInboxDto
      • ProviderType
      • CustomerUserLoginModel
      • SuccessResponseModelOfCustomerUserLoginResultModel
      • SuccessResponseModelOfV2CampaignGetModel
      • SuccessResponseModelOfPagedListGetModelOfSmsConversationGetModel
      • V2ContactDetailUpdateModel
      • V2ContactUpdateModel
      • WhatsAppStatus
      • PagedListGetModelOfPaymentGetModel
      • V2ContactDetailExportRequestModel
      • EmailDataRecordGetModel
      • SmsConversationGetModel
      • SenderIdType
      • LinkAnalyticsResponse
      • CustomerUserLoginResultModel
      • V2ContactMessageListFilterModel
      • FilterComparer
      • SuccessResponseModelOfV2SegmentGetModel
      • PagedListGetModelOfV2ContactDetailGetModel
      • SenderIdGetModel
      • PaymentDirection
      • TrafficType
      • UpdateLinkRequest
      • SuccessResponseModelOfPagedListGetModelOfV2CampaignListItemModel
      • WhatsAppTemplateCategory
      • PagedListGetModelOfSmsConversationGetModel
      • V2SegmentListFilterModel
      • ConversationStatus
      • V2ExportMode
      • V2SegmentGetModel
      • V2ContactDetailListFilterModel
      • SuccessResponseModelOfStatisticSenderIdExpensesGetModel
      • SenderIdStatus
      • PagedListGetModelOfV2ContactMessageListItemModel
      • V2DashboardOtpStatsModel
      • SuccessResponseModelOfPagedListGetModelOfSenderIdGetModel
      • SuccessResponseModelOfStatisticBalanceGetModel
      • StatisticSenderIdExpensesGetModel
      • SocialMessageDto
      • AdminUserGetModel
      • PagedListGetModelOfTemplateGetModel
      • SuccessResponseModelOfPagedListGetModelOfTemplateGetModel
      • CreateLinkRequest
      • ProblemDetails_link
      • SenderIdTrafficTypeGetModel
      • V2CampaignListItemModel
      • SuccessResponseModelOfV2CampaignPricePreviewModel
      • MessageStatus
      • SenderIdTypeGetModel
      • SocialChannelDto
      • SuccessResponseModelOfPagedListGetModelOfAreaMccMncGetModel
      • SuccessResponseModelOfV2CampaignMessageInfoModel
      • TokenGetModel
      • V2CampaignChannelCreateModel
      • StatisticBalanceGetModel
      • V2CampaignPricePreviewModel
      • RateGetModel
      • SocialConversationStatusHistoryDto
      • SuccessResponseModelOfPaymentListGetModelOfPaymentGetModel
      • V2SegmentCreateModel
      • AreaMccMncFilterModel
      • SuccessResponseModelOfString
      • MessageDirection
      • TokenRefreshModel
      • PagedListGetModelOfEmailDataRecordGetModel
      • SocialProviderDto
      • EmailPriceGetModel
      • ResyncChannelsResponseDto
      • SenderIdMediaAttachmentGetModel
      • TemplateUpdateModel
      • SuccessResponseModelOfPagedListGetModelOfV2SegmentGetModel
      • IFormFile
      • V2CampaignGetModel
      • PagedListGetModelOfSenderIdPriceGetModel
      • SuccessResponseModelOfEmailDataRecordGetModel
      • PagedListGetModelOfV2SegmentGetModel
      • PartnerCustomerUserLoginModel
      • V2ContactExportRequestModel
      • SuccessResponseModelOfTokenGetModel
      • PaginationModel
      • SyncMessagesResponseDto
      • SuccessResponseModelOfIEnumerableOfLong
      • SuccessResponseModelOfPaymentGetModel
      • SortingModel
      • V2CampaignChannelSummaryModel
      • SenderIdPriceGetModel
      • V2SegmentExportRequestModel
      • V2DashboardKpisModel
      • SuccessResponseModelOfTemplateGetModel
      • V2CampaignMessageInfoModel
      • AreaMccMncGetModel
      • V2DashboardOtpChannelModel
      • CampaignAnalyticsListRequest
      • PaymentListGetModelOfPaymentGetModel
      • ReplyMessageResponseDto
      • V2ContactDetailGetModel
      • V2DashboardChannelBreakdownModel
      • ContactAnalyticsResponse
      • SuccessResponseModelOfLong
      • LinkResponse
      • SuccessResponseModelOfCustomerUserGetModel
      • V2ContactGetModel
      • SuccessResponseModelOfBoolean
      • V2ContactDetailStatus
      • SuccessResponseModelOfPagedListGetModelOfSenderIdPriceGetModel
      • V2CampaignChannelPricePreviewModel
      • PagedListGetModelOfSenderIdGetModel
      • V2DashboardTrendsDataPointModel
      • TemplateGetBaseModel
      • SenderIdViberLogoGetModel
      • V2DashboardChannelFunnelModel
      • TemplateGetModel
      • ConversationStatusHistoryActionType
      • PaymentGetModel
      • V2CampaignListFilterModel
      • CustomerTrunkBaseGetModel
      • CampaignAnalyticsResponse
      • V2CampaignCreateModel
      • BusinessType
      • PaymentFilterModel
      • V2CampaignMessageInfoRequest
      • TemplateMediaAttachmentGetModel
      • SuccessResponseModelOfV2CampaignRecipientPreviewModel
      • FilteringModel
      • MessageType
      • SuccessResponseModelOfPagedListGetModelOfV2ContactMessageListItemModel
      • TemplateStatus
      • SuccessResponseModelOfCustomerTrunkBaseGetModel
      • FilteringSortingModel
      • V2ContactListFilterModel
      • V2DashboardTrendsModel
      • V2ContactMessageListItemModel
      • ConversationFilteringSortingModel
      • SuccessResponseModelOfPagedListGetModelOfEmailDataRecordGetModel
      • V2CampaignRecipientPreviewModel
      • SuccessResponseModelOfV2ContactGetModel
      • SuccessResponseModelOfPagedListGetModelOfV2ContactDetailGetModel
      • SortDirection
      • PagedListGetModelOfAreaMccMncGetModel
      • V2CampaignUnresolvableRecipientModel
      • RateDetailGetModel
      • RefreshTokenResponseDto
      • SuccessResponseModelOfPagedListGetModelOfV2ContactGetModel
  • VeloVerify API
    • VeloVerify quick start
    • VeloVerify reason codes
    • Authentication
      • Exchange API credentials
      • Refresh an access token
    • HLR Lookup
      • Check number reachability
    • MNP Lookup
      • Look up the current network
    • Account Management
      • Get account balance
      • List balance transactions
      • List invoices
      • Get automatic top-up settings
      • Update automatic top-up settings
    • Billing & Payments
      • Create a top-up checkout
      • Start saving a payment method
      • List saved payment methods
      • Remove a saved payment method
    • Async Queries
      • Submit an asynchronous HLR lookup
      • Submit an asynchronous MNP lookup
      • Submit a batch of lookups
      • Get task status
      • Get batch status
    • Schemas
      • AsyncBatchRequest
      • AsyncBatchResponse
      • AsyncSingleRequest
      • AsyncSubmitResponse
      • AutoTopupSettings
      • AutoTopupUpdate
      • BatchStatusResponse
      • HTTPValidationError
      • PaymentMethodOut
      • RefreshRequest
      • SetupIntentResponse
      • TaskCreatedResponse
      • TaskStatusResponse
      • TokenRequest
      • TokenResponse
      • TopupResponse
      • UnifiedResponse
      • ValidationError
      • TopupRequest
  • VeloeSIM API
    • VeloeSIM quick start
    • Plans
      • Get a plan
      • List available plans
    • Organization
      • Get organization balance
    • Orders
      • Purchase an eSIM plan
    • eSIMs
      • List organization eSIMs
      • Get an eSIM
      • List eSIM top-up plans
      • Top up an eSIM
  1. Contacts

Import contacts from CSV

POST
https://api.veloconnect.me/api/v2/contacts/import-csv
Contacts (v2)
Last modified:2026-10-09 05:34:57
Creates many contacts from one CSV file. It can add them to a segment in the same call.
Authentication: send the login token in the header Authorization: Bearer <token>. Get it with the sign-in call (POST /api/customer-users/partner-login).
The file
.csv or .txt, comma-separated, up to 10 MB, with a header row.
Columns are found by name, in any order, in upper or lower case: PhoneNumber, FirstName, LastName, Email, DateOfBirth, Gender, Interest, Url. Put all eight names in the header and leave a cell empty when you have no value.
PhoneNumber is + followed by 7 to 15 digits, the first of them not 0; a missing + is added for you. A row with a wrong number is skipped and named in errors.
Interest is saved as the contact's note.
What happens
Each row becomes a new contact, unless it is left out for one of the reasons below. Its phone number is saved as three details, Phone, Viber and WhatsApp, so the contact is ready for SMS, Viber and WhatsApp campaigns. Email and Url become details too.
A row whose phone number already belongs to a contact is not imported and the existing contact is not changed. The row is listed in alreadyExistingContacts.
A row with no phone number, no first name, no last name and no e-mail is skipped. A row without a phone number is imported when it has one of the other three.
With segmentId, the new contacts and the contacts of the file that already existed are added to that segment.
The answer. The call answers 200 also when the file itself was refused (wrong type, too large, empty, unknown segment), so always read errors. importedCount is the number of contacts created and skippedCount the number of rows left out. Row numbers count the header as row 1.

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Body Params multipart/form-dataRequired

Responses

🟢200Import result
application/json
The file was processed or refused. Read importedCount, skippedCount, errors and alreadyExistingContacts to see what happened to each row.
Bodyapplication/json

🟠400Not a valid upload
🟠401Token missing or expired
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.veloconnect.me/api/v2/contacts/import-csv' \
--header 'Authorization: Bearer <token>' \
--form 'file=@"contacts.csv"' \
--form 'segmentId="57"'
Response Response Example
200 - One imported, two skipped
{
  "data": [
    {
      "totalRows": 3,
      "importedCount": 1,
      "skippedCount": 2,
      "errors": [
        "Row 4: '091234567' is not a valid phone number — skipped."
      ],
      "alreadyExistingContacts": [
        {
          "rowNumber": 3,
          "phoneNumber": "+37499123456",
          "existingContactId": 1043,
          "hasDifferentDetails": false,
          "message": "Row 3: phone +37499123456 already exists (contact #1043)."
        }
      ]
    }
  ]
}
Modified at 2026-10-09 05:34:57
Previous
Export contacts
Next
List contacts
Built with