> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Lookup by phone number > Find the matching simulation using the number used by the Roark simulation agent. ## OpenAPI ````yaml /api-reference/openapi.documented.json get /v1/simulation/job/lookup openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Simulation Persona - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Call Analysis - name: Health paths: /v1/simulation/job/lookup: get: tags: - Simulation Job summary: Lookup by phone number description: >- Find the matching simulation using the number used by the Roark simulation agent. operationId: getV1SimulationJobLookup parameters: - in: query name: roarkPhoneNumber schema: _def: checks: [] typeName: ZodString coerce: false ~standard: version: 1 vendor: zod required: true example: '+15551234567' description: >- Phone number provisioned by Roark for the simulation job in E.164 format. In the case of an inbound simulation, this is the number that calls your agent; in the case of an outbound simulation, this is the number you call from your agent. - in: query name: callReceivedAt schema: _def: checks: - kind: datetime precision: null offset: false local: false typeName: ZodString coerce: false ~standard: version: 1 vendor: zod required: false example: '2024-01-15T10:30:00Z' description: >- ISO 8601 timestamp of when the call was received. Alternatively, any time between the start and end of the call is valid. Defaults to the current time, which fetches any jobs that are currently ongoing. responses: '200': description: Successfully found simulation job content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SimulationJobResponse' required: - data '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': description: No active lease or associated job found content: application/json: schema: _def: unknownKeys: strip catchall: _def: typeName: ZodNever ~standard: version: 1 vendor: zod typeName: ZodObject ~standard: version: 1 vendor: zod _cached: null '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.simulationJob.lookup({ roarkPhoneNumber: {} }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.simulation_job.lookup( roark_phone_number={}, ) print(response.data) components: schemas: SimulationJobResponse: type: object properties: simulationJobId: type: string format: uuid description: Simulation job ID status: type: string description: Job status processingStatus: type: string description: Processing status callId: type: - string - 'null' format: uuid description: >- ID of the call created for this simulation job. Null if the call has not been created yet. roarkPhoneNumber: type: - string - 'null' description: >- Phone number provisioned by Roark for this simulation job in E.164 format. Null if the simulation job is queued and has not been assigned a phone number yet. runPlan: $ref: '#/components/schemas/SimulationRunPlanRef' persona: type: object properties: id: type: string format: uuid description: Unique identifier of the persona name: type: string description: The name the agent will identify as during conversations description: type: - string - 'null' description: Human-readable description of the persona language: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE description: Primary language ISO 639-1 code for the persona secondaryLanguage: type: - string - 'null' enum: - EN description: >- Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) accent: type: string enum: - US - US_X_SOUTH - GB - ES - DE - IN - FR - NL - SA - GR - AU - IT - ID - TH - JP - NZ - PH - SG - MY - HK - TR - PT - IL description: >- Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM default: NONE description: Background noise setting speechPace: type: string enum: - SUPER_SLOW - SLOW - NORMAL - FAST - SUPER_FAST default: NORMAL description: Speech pace of the persona speechClarity: type: string enum: - CLEAR - VAGUE - RAMBLING default: CLEAR description: Speech clarity of the persona hasDisfluencies: type: boolean default: false description: Whether the persona uses filler words like "um" and "uh" baseEmotion: type: string enum: - NEUTRAL - CHEERFUL - CONFUSED - FRUSTRATED - SKEPTICAL - RUSHED - DISTRACTED default: NEUTRAL description: Base emotional state of the persona intentClarity: type: string enum: - CLEAR - INDIRECT - VAGUE default: CLEAR description: How clearly the persona expresses their intentions confirmationStyle: type: string enum: - EXPLICIT - VAGUE default: EXPLICIT description: How the persona confirms information memoryReliability: type: string enum: - HIGH - LOW default: HIGH description: How reliable the persona's memory is responseTiming: type: string enum: - RELAXED - NORMAL - QUICK default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - accent - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt scenario: $ref: '#/components/schemas/ScenarioResponse' agentEndpoint: $ref: '#/components/schemas/AgentEndpointResponse' createdAt: type: string description: When the job was created startedAt: type: - string - 'null' description: When the job started completedAt: type: - string - 'null' description: When the job completed required: - simulationJobId - status - processingStatus - runPlan - persona - scenario - agentEndpoint - createdAt description: Simulation job with related entities example: simulationJobId: 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f status: COMPLETED processingStatus: PROCESSED callId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 roarkPhoneNumber: '+15551234567' runPlan: id: b2c3d4e5-f6a7-8901-bcde-f12345678901 name: Billing Flow Test variables: promptToUse: v1 accountTier: premium persona: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Sarah Johnson - Anxious Patient language: EN secondaryLanguage: null accent: US gender: FEMALE backgroundNoise: OFFICE speechPace: NORMAL speechClarity: CLEAR hasDisfluencies: false baseEmotion: FRUSTRATED intentClarity: CLEAR confirmationStyle: EXPLICIT memoryReliability: HIGH backstoryPrompt: A busy professional calling during lunch break idleMessages: null properties: age: 35 zipCode: '94105' createdAt: '2025-01-10T12:00:00.000Z' updatedAt: '2025-01-10T12:00:00.000Z' scenario: id: f8e7d6c5-b4a3-9281-7069-5f4e3d2c1b0a description: >- Patient calling to schedule an urgent dental appointment due to severe tooth pain agentEndpoint: id: 3c2b1a09-8f7e-6d5c-4b3a-291807060504 name: PHONE phoneNumber: '+15555551234' type: PHONE createdAt: '2025-01-15T14:23:45.123Z' startedAt: '2025-01-15T14:24:15.456Z' completedAt: '2025-01-15T14:28:32.789Z' ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message SimulationRunPlanRef: type: object properties: id: type: string format: uuid description: Run plan ID name: type: string description: Run plan name variables: type: object additionalProperties: type: string description: >- Run-plan-level variables resolved for this job, keyed by variable name. Values are stringified by their declared type. required: - id - name - variables ScenarioResponse: type: object properties: id: type: string format: uuid description: Scenario ID description: type: - string - 'null' description: Scenario description required: - id description: Scenario used in a simulation AgentEndpointResponse: type: object properties: id: type: string format: uuid description: Agent endpoint ID name: type: string description: Agent endpoint name phoneNumber: type: - string - 'null' description: Agent endpoint phone number type: type: string enum: - PHONE - WEBSOCKET - LIVEKIT - SMALL_WEBRTC - ELEVENLABS_WS - KORE - GOOGLE_CES - DAILY description: Agent endpoint type required: - id - name - phoneNumber - type description: Agent endpoint used in a simulation securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````