> For the complete documentation index, see [llms.txt](https://doc1.antgst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc1.antgst.com/ant-api/voice/outbound-task.md).

# Outbound Task

API for submitting proportional call tasks.

A proportional call task uses a configurable call ratio to dial numbers from an uploaded number file and route answered calls directly to a seat group for agent handling.

## Submit Task

> Submit a new proportional call task.

```json
{"openapi":"3.0.3","info":{"title":"Proportional Call Task API","version":"1.0.0"},"servers":[{"url":"https://api.antgst.com/voice/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"[X-API-Key](https://web.antgst.com/client/account/workspaceApi) = API key + API secret."}},"schemas":{"SubmitProportionalCallRequest":{"type":"object","properties":{"displayNumber":{"type":"string","description":"The caller number displayed to the recipient.","pattern":"^\\+?\\d{6,20}$","maxLength":20},"numberFileId":{"type":"integer","format":"int64","description":"Voice number file ID."},"seatGroupId":{"type":"integer","format":"int64","description":"ID of the seat group (mutually exclusive with 'seat')."},"seat":{"type":"String","description":"The seat's account used to initiate outbound calls (mutually exclusive with 'seatGroupId')."},"callRatio":{"type":"integer","description":"Call ratio multiplier.","default":1,"minimum":1,"maximum":10},"maximumRingingDuration":{"type":"integer","description":"Maximum ringing duration in seconds before a call is considered unanswered.","default":30,"minimum":10,"maximum":60}},"required":["displayNumber","numberFileId"]},"SubmitProportionalCallResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Interface status code."},"msg":{"type":"string","description":"Interface response message."},"status":{"type":"string","description":"Initial task status."},"taskId":{"type":"integer","format":"int64","description":"The unique ID of the newly created task. Use this ID for subsequent operations (detail, stop, etc.)."}}}}},"paths":{"/proportionalCall/submit":{"post":{"summary":"Submit Task","description":"Submit a new proportional call task.","operationId":"submitProportionalCallTask","tags":["Proportional Call Tasks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitProportionalCallRequest"}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitProportionalCallResponse"}}}}}}}}}
```

## Stop Task

> Stop a running call task.

```json
{"openapi":"3.0.3","info":{"title":"Proportional Call Task API","version":"1.0.0"},"servers":[{"url":"https://api.antgst.com/voice/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"[X-API-Key](https://web.antgst.com/client/account/workspaceApi) = API key + API secret."}},"schemas":{"BasicResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Interface status code."},"msg":{"type":"string","description":"Interface response message."}}}}},"paths":{"/proportionalCall/stop/{taskId}":{"put":{"summary":"Stop Task","description":"Stop a running call task.","operationId":"stopProportionalCallTask","tags":["Proportional Call Tasks"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicResponse"}}}}}}}}}
```

## Resume Task

> Resume a previously stopped call task.

```json
{"openapi":"3.0.3","info":{"title":"Proportional Call Task API","version":"1.0.0"},"servers":[{"url":"https://api.antgst.com/voice/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"[X-API-Key](https://web.antgst.com/client/account/workspaceApi) = API key + API secret."}},"schemas":{"BasicResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Interface status code."},"msg":{"type":"string","description":"Interface response message."}}}}},"paths":{"/proportionalCall/resume/{taskId}":{"put":{"summary":"Resume Task","description":"Resume a previously stopped call task.","operationId":"resumeProportionalCallTask","tags":["Proportional Call Tasks"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicResponse"}}}}}}}}}
```

## Task Detail

> Retrieve details and execution statistics of a specific call tasks.

```json
{"openapi":"3.0.3","info":{"title":"Proportional Call Task API","version":"1.0.0"},"servers":[{"url":"https://api.antgst.com/voice/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"[X-API-Key](https://web.antgst.com/client/account/workspaceApi) = API key + API secret."}},"schemas":{"TaskDetailResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Interface status code."},"msg":{"type":"string","description":"Interface response message."},"data":{"$ref":"#/components/schemas/TaskDetailData"}}},"TaskDetailData":{"type":"object","properties":{"id":{"type":"string","description":"Unique task ID."},"name":{"type":"string","description":"Task name."},"countryCode":{"type":"string","description":"Country code of the dialed numbers."},"displayNumber":{"type":"string","description":"Caller ID displayed to recipients."},"callRatio":{"type":"integer","description":"Call ratio multiplier."},"stopCause":{"type":"string","description":"Reason the task was stopped. Only present when the task has been stopped."},"status":{"type":"string","enum":["submitting","running","stopped","submit failed","completed","failed"],"description":"Current task status (mapped from internal numeric status)."},"maximumRingingDuration":{"type":"integer","description":"Maximum ringing duration in seconds."},"totality":{"type":"integer","description":"Total number of records in the task."},"completeCount":{"type":"integer","description":"Number of calls completed."},"callLoseCount":{"type":"integer","description":"Number of calls lost."},"failCount":{"type":"integer","description":"Number of failed calls."},"successCount":{"type":"integer","description":"Number of connected calls."},"transferCount":{"type":"integer","description":"Number of calls transferred to an agent."},"seatSuccessCount":{"type":"integer","description":"Number of transfers successfully connected to an agent."}}}}},"paths":{"/proportionalCall/task/{taskId}":{"get":{"summary":"Task Detail","description":"Retrieve details and execution statistics of a specific call tasks.","operationId":"getProportionalCallTaskDetail","tags":["Proportional Call Tasks"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetailResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc1.antgst.com/ant-api/voice/outbound-task.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.