Create a new conversation
POST /v4/authvia/conversations
Environment and operation
Use this endpoint contract with the account and environment assigned to your integration. Values in angle brackets are placeholders. This reference does not execute requests. Documented server https://sandbox.nmi.com/api Schema reference: field definitions do not include every behavioral rule. Follow the workflow guidance and account prerequisites for this operation before submitting requests.
Request route
Select the documented server above and use this method and path. Path identifiers must belong to the authorized account. POST /v4/authvia/conversations Security scheme Type Credential location Scopes v4ApiKey apiKey header Authorization No scopes declared on this operation
Request language templates
Original transport templates derived from this endpoint’s documented method, server, authentication and media type. Replace path/query/credential placeholders with authorized sandbox values. These examples print the raw status and response; they do not infer business success or retry a request. Save one valid request variant from the fields/examples below as request.json. Do not combine mutually exclusive variants. The payload is deliberately not fabricated from schema defaults. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request POST \ --url 'https://sandbox.nmi.com/api/v4/authvia/conversations' \ --header 'Authorization: <v4ApiKey>' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' import { readFile } from 'node:fs/promises'; const body = await readFile('request.json', 'utf8'); const response = await fetch("https://sandbox.nmi.com/api/v4/authvia/conversations", { method: 'POST', headers: { "Authorization": "<v4ApiKey>", "Content-Type": "application/json" }, body }); console.log(response.status, await response.text()); from urllib.request import Request, urlopen from urllib.error import HTTPError from pathlib import Path request = Request('https://sandbox.nmi.com/api/v4/authvia/conversations', method='POST', headers={'Authorization': '<v4ApiKey>', 'Content-Type': 'application/json'}, data=Path('request.json').read_bytes()) try: with urlopen(request, timeout=30) as response: print(response.status, response.read().decode()) except HTTPError as error: print(error.code, error.read().decode()) require 'net/http' require 'uri' uri = URI("https://sandbox.nmi.com/api/v4/authvia/conversations") request = Net::HTTP::Post.new(uri) request["Authorization"] = "<v4ApiKey>" request["Content-Type"] = "application/json" request.body = File.binread('request.json') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) { |http| http.request(request) } puts response.code puts response.body <?php $curl = curl_init('https://sandbox.nmi.com/api/v4/authvia/conversations'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Authorization: <v4ApiKey>', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => file_get_contents('request.json') ]); $response = curl_exec($curl); if ($response === false) { throw new RuntimeException(curl_error($curl)); } echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $response; curl_close($curl);
Request body
Use the declared media type: application/json. Required flags below apply within the selected object or variant. Read the workflow notes before choosing a variant. Field Type Required Description Constraints merchantId string no The merchant ID from NMI. This is only required for partners; for merchants it is ignored. format: "int32" phone string yes The conversation customer's ten-digit phone number. US and CA numbers only. pattern: "^\\d{10}$" amount variant yes firstName string yes The conversation customer's first name. lastName string yes The conversation customer's last name. expiration string yes The time to wait for the payment to be completed before it is marked failed. A short time duration value is acceptable such as 30m, 1d, or 7d. If no unit is provided, seconds are used. pattern: "^\\d+?([smhd])$" instructions string yes A short intro or message to send along with the payment request to help provide more context. maxLength: 50 topic string yes The resolution this conversation is trying to reach. { "description": "The new conversation request body.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "amount", "firstName", "lastName", "expiration", "instructions", "topic" ], "properties": { "merchantId": { "$ref": "#/components/schemas/NmiMerchantId" }, "phone": { "$ref": "#/components/schemas/ConversationCustomerPhone" }, "amount": { "$ref": "#/components/schemas/ConversationAmountInput" }, "firstName": { "$ref": "#/components/schemas/ConversationCustomerFirstName" }, "lastName": { "$ref": "#/components/schemas/ConversationCustomerLastName" }, "expiration": { "$ref": "#/components/schemas/ConversationExpirationDateInput" }, "instructions": { "$ref": "#/components/schemas/ConversationInstructions" }, "topic": { "$ref": "#/components/schemas/ConversationTopic" } } } } } } true
Responses
Match the HTTP status to its response schema below. For financial operations, also inspect the payment outcome before updating your order or retrying. HTTP status Media type Meaning 200 application/json The conversation was created successfully. { "200": { "description": "The conversation was created successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "phone", "date", "status", "firstName", "lastName", "recordId", "expiration", "amount", "topic", "instructions" ], "properties": { "id": { "$ref": "#/components/schemas/ConversationId" }, "phone": { "$ref": "#/components/schemas/ConversationCustomerPhoneWithDashes" }, "date": { "$ref": "#/components/schemas/ConversationCreationDate" }, "status": { "$ref": "#/components/schemas/ConversationStatus" }, "firstName": { "$ref": "#/components/schemas/ConversationCustomerFirstName" }, "lastName": { "$ref": "#/components/schemas/ConversationCustomerLastName" }, "recordId": { "$ref": "#/components/schemas/NmiRecordId" }, "expiration": { "$ref": "#/components/schemas/ConversationExpirationDate" }, "amount": { "$ref": "#/components/schemas/ConversationAmount" }, "topic": { "$ref": "#/components/schemas/ConversationTopic" }, "instructions": { "$ref": "#/components/schemas/ConversationInstructions" } } } } } } } true
Response fields · 200 · application/json
Field Type Required Description Constraints id string yes The Authvia v4 UUID for the conversation. pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" phone string yes The conversation customer's phone number separated with dashes. pattern: "^\\d{3}-\\d{3}-\\d{4}$" date string yes The creation date for the conversation. format: "date-time" status string yes The conversation status. enum: ["in progress", "expired", "completed"] firstName string yes The conversation customer's first name. lastName string yes The conversation customer's last name. recordId string yes The NMI marketplace v4 UUID for the conversation. pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" expiration string yes The expiration date for the conversation. format: "date-time" amount string yes The conversation amount in USD. pattern: "^\\d+\\.\\d{2}$" topic string yes The resolution this conversation is trying to reach. instructions string yes A short intro or message to send along with the payment request to help provide more context. maxLength: 50
Referenced schema definitions
References beginning with #/components resolve to these definitions. These are field contracts, not example payment values. Use the applicable variant, required fields and constraints. { "schemas": { "ConversationId": { "type": "string", "description": "The Authvia v4 UUID for the conversation.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "example": "7baf2306-4804-4aef-a55e-8cbfcb201ad1" }, "ConversationTopic": { "type": "string", "description": "The resolution this conversation is trying to reach.", "example": "Weasleys' Wizard Wheezes - Extendable Ear" }, "ConversationInstructions": { "type": "string", "description": "A short intro or message to send along with the payment request to help provide more context.", "maxLength": 50, "example": "Thank you for your purchase! Please click the link below to make your payment." }, "ConversationCreationDate": { "type": "string", "description": "The creation date for the conversation.", "format": "date-time", "example": "2023-11-16T20:28:51.990Z" }, "ConversationExpirationDate": { "type": "string", "description": "The expiration date for the conversation.", "format": "date-time", "example": "2023-11-23T20:28:51.990Z" }, "ConversationExpirationDateInput": { "type": "string", "description": "The time to wait for the payment to be completed before it is marked failed. A short time duration value is acceptable such as 30m, 1d, or 7d. If no unit is provided, seconds are used.", "pattern": "^\\d+?([smhd])$", "example": "7d" }, "ConversationStatus": { "type": "string", "description": "The conversation status.", "enum": [ "in progress", "expired", "completed" ], "example": "in progress" }, "ConversationAmount": { "type": "string", "description": "The conversation amount in USD.", "pattern": "^\\d+\\.\\d{2}$", "example": "59.94" }, "ConversationAmountInput": { "oneOf": [ { "type": "string", "description": "The amount of the payment, in USD. Should qualify to two decimal places.", "format": "float", "example": "59.94" }, { "type": "integer", "description": "The amount of the payment in fractional base currency (i.e., pennies).", "example": 5994 } ] }, "ConversationCustomerPhone": { "type": "string", "description": "The conversation customer's ten-digit phone number. US and CA numbers only.", "pattern": "^\\d{10}$", "example": "1234567890" }, "ConversationCustomerPhoneWithDashes": { "type": "string", "description": "The conversation customer's phone number separated with dashes.", "pattern": "^\\d{3}-\\d{3}-\\d{4}$", "example": "123-456-7890" }, "ConversationCustomerFirstName": { "type": "string", "description": "The conversation customer's first name.", "example": "Aberforth" }, "ConversationCustomerLastName": { "type": "string", "description": "The conversation customer's last name.", "example": "Dumbledore" }, "NmiMerchantId": { "type": "string", "description": "The merchant ID from NMI. This is only required for partners; for merchants it is ignored.", "format": "int32", "example": "1" }, "NmiRecordId": { "type": "string", "description": "The NMI marketplace v4 UUID for the conversation.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "example": "4eed6bef-7fd3-4780-9563-c0d2afa88c76" } }, "securitySchemes": { "v4ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API Security Key assigned to a partner or merchant account. New keys can be generated from Settings > Security Keys in the partner and merchant portals." } } } true
Integration checks
Validate the request against its selected schema before submission. Keep secrets outside browser code. Test permitted and denied account access, validation failures and interrupted responses in the sandbox. Account-management or messaging operations require the corresponding partner access and intended recipient context.